cel 0.3.1 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82fcb37e45c0553a7c073b58e4c6b7203cc50bd186419724d72f5f1b0217e3f5
-  data.tar.gz: 44170fc7001634abc19860db8dcbc8c05ae8974716ad80dd28c4316dc0cec7f3
+  metadata.gz: e4d35d9012196d61497f40e35c8e9dd9b1a9d7e1e922078a414cd574eacc439a
+  data.tar.gz: f2a0e48bc07e0c0b5eb23c7ea6d709a1b56fff3400b51204d26c3031f11db696
 SHA512:
-  metadata.gz: 593ec20b7001fe593d6df79928ca8411327251fff2405491eb33642299cf6bc09d255d0088fdb6a1deda77eabccf8bcce229ad5038f68ee932f9c10ef162cdc0
-  data.tar.gz: 55eb21528a3ff994f5fc013ca49ded2b7cb0aaf9d5d434c671fc0cd534ed0119269c1e2bf8b5fe9e44ba1f1e05f51d30f5fd84abd1f44d740898dd971b341ece
+  metadata.gz: d39c028b26513ed27749f5bd7c5cfa57281b0433a5b5984418d657fd61441122e4cddae1942cdb7b3e3c9aeb0979d7387ca5d7444cea0afd04477615278acbfa
+  data.tar.gz: 442da2f399685e77bee5f743c693f0ef0fe9b333dfea333f61b17f8419a6bf7752aca14e0c5211ff0a8a526bc36a9a575a9e0cac53190f47e3af0b54097c26de

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 ## [Unreleased]
 
+## [0.4.1] - 2025-11-25
+
+### Improvements
+
+* Literal class can now mark which methods are CEL directives, the remainder being lib private helpers.
+* `cel` is now ractor compatible.
+* Documentation on how to support abstract types has been added.
+
+### Security
+
+A remote execution attack vector has been fixed, which allowed executing arbitrary Ruby code within a CEL expression when calling functions on a variable declared as a CEL map. Example:
+
+```ruby
+env = Cel::Environment.new(declarations: { webhook: :map })
+env.evaluate("webhook.payload.send('eval', 'File.write(\"test.txt\", \"Hello, world!\")')", webhook: { payload: {} })
+```
+
+## [0.4.0] - 2025-11-18
+
+### Features
+
+`cel-ruby` supports the defined set of [CEL extensions](https://github.com/google/cel-go/blob/master/ext/README.md): math, string, bind and encoders.
+
+```ruby
+Cel::Environment.new.evaluate("math.bitShiftLeft(1, 2) ") #=> returns 4
+```
+
+### Improvements
+
+When the `tzinfo-data` gem is loaded, expressions will support human-friendly timezones, such as "US/Central", for timestamps.
+
 ## [0.3.1] - 2025-08-01
 
 ### Improvements
@@ -9,7 +40,7 @@
 
 ### Bugfixes
 
-* `has()` macro correctly works for mapsl
+* `has()` macro correctly works for maps
 
 ## [0.3.0] - 2025-06-12
 

data/README.md

@@ -131,14 +131,37 @@ env.evaluate("google.protobuf.Duration{seconds: 123}.seconds == 123") #=> true
 `cel-ruby` allows you to define custom functions to be used insde CEL expressions. While we **strongly** recommend usage of `Cel::Function` for defining them (due to the ability of them being used for checking), the only requirement is that the function object responds to `.call`:
 
 ```ruby
-env = environment(foo: Cel::Function(:int, :int, return_type: :int) { |a, b|  a + b})
+env = Cel::Environment.new(declarations: {foo: Cel::Function(:int, :int, return_type: :int) { |a, b|  a + b }})
 env.evaluate("foo(2, 2)") #=> 4
 
 # this is also possible, just not as type-safe
-env2 = environment(foo: -> (a, b) { a + b})
+env2 = Cel::Environment.new(declarations: {foo: ->(a, b) { a + b }})
 env2.evaluate("foo(2, 2)") #=> 4
 ```
 
+### Abstract types
+
+`cel-ruby` supports defining abstract types, via the `Cel::AbstractType` class.
+
+```ruby
+class Tuple
+  attr_reader :value
+  def initialize(ary)
+    @value = ary
+  end
+end
+
+tuple_type = Class.new(Cel::AbstractType) do
+  def convert(value)
+    Tuple.new(value)
+  end
+end.new(:tuple, Cel::TYPES[:int], Cel::TYPES[:int])
+env = Cel::Environment.new(declarations: { tuple: Cel::Function(:int, :int, return_type: tuple_type) {|a, b| [a, b] } })
+env.check('tuple(1, 2)') #=> tuple type
+res = env.evaluate('tuple(1, 2)') #=> Tuple instance
+res.value #=> [1, 2]
+```
+
 ## Spec Coverage
 
 `cel` is tested against the conformance suite from the [cel-spec repository](https://github.com/google/cel-spec/tree/master/conformance), and supports all features from the language except:
@@ -185,7 +208,7 @@ The parser is based on the grammar defined in [cel-spec](https://github.com/goog
 Changes in the parser are therefore accomplished by modifying the `parser.ry` file and running:
 
 ```bash
-> bundle exec racc -o lib/cel/parser.rb lib/cel/parser.ry
+> bundle exec racc -F -o lib/cel/parser.rb lib/cel/parser.ry
 ```
 
 ## Contributing

data/lib/cel/ast/cel_methods.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Cel
+  module CelMethods
+    def self.included(klass)
+      super
+      klass.class_eval do
+        @cel_methods = [] # rubocop:disable ThreadSafety/ClassInstanceVariable
+
+        extend ClassMethods
+        include InstanceMethods
+      end
+    end
+
+    module ClassMethods
+      attr_reader :cel_methods
+
+      def define_cel_method(meth, &blk)
+        Ractor.make_shareable(blk) if defined?(Ractor)
+        define_method(meth, &blk)
+
+        @cel_methods << meth # rubocop:disable ThreadSafety/ClassInstanceVariable
+      end
+
+      def inherited(klass)
+        super
+
+        klass.instance_variable_set(:@cel_methods, [])
+      end
+
+      def freeze(*a)
+        super
+        @cel_methods.freeze(*a) # rubocop:disable ThreadSafety/ClassInstanceVariable
+      end
+    end
+
+    module InstanceMethods
+      def cel_send(meth, *args)
+        meth = meth.to_sym
+        raise NoCelMethodError unless cel_method_defined?(meth)
+
+        public_send(meth, *args)
+      end
+
+      def cel_method_defined?(meth)
+        klass = self.class
+
+        while klass != Literal
+          return true if klass.cel_methods.include?(meth)
+
+          klass = klass.superclass
+        end
+
+        klass.cel_methods.include?(meth)
+      end
+    end
+  end
+end

data/lib/cel/ast/elements/bool.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Cel
+  class Bool < Literal
+    def initialize(value)
+      super(:bool, value)
+    end
+
+    (LOGICAL_OPERATORS - %w[== != in]).each do |op|
+      class_eval(<<-OUT, __FILE__, __LINE__ + 1)
+        define_cel_method(:#{op}) do |other|
+          return super(other) unless other.is_a?(Bool)
+
+          lhs = @value ? 1 : 0
+          rhs = other.value ? 1 : 0
+          lhs.__send__(__method__, rhs)
+        end
+      OUT
+    end
+
+    def !
+      Bool.cast(super)
+    end
+
+    TRUE_VALUE = new(true)
+    FALSE_VALUE = new(false)
+
+    def self.cast(val)
+      return val if val.is_a?(Bool)
+
+      val ? TRUE_VALUE : FALSE_VALUE
+    end
+  end
+end

data/lib/cel/ast/elements/bytes.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Cel
+  class Bytes < Literal
+    attr_reader :string
+
+    def initialize(value)
+      super(:bytes, value)
+      @string = value.pack("C*")
+    end
+
+    def to_ary
+      [self]
+    end
+
+    alias_method :to_ruby_type, :string
+
+    (LOGICAL_OPERATORS - %w[==]).each do |op|
+      class_eval(<<-OUT, __FILE__, __LINE__ + 1)
+        define_cel_method(:#{op}) do |other|
+          other.is_a?(Cel::Bytes) ? Bool.cast(@string.__send__(__method__, other.string)) : super(other)
+        end
+      OUT
+    end
+
+    %i[+ -].each do |op|
+      class_eval(<<-OUT, __FILE__, __LINE__ + 1)
+        define_cel_method(:#{op}) do |other|
+          Bytes.new(@value + other.value)
+        end
+      OUT
+    end
+  end
+end

data/lib/cel/ast/elements/condition.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Cel
+  class Condition
+    attr_reader :if, :then, :else, :depth
+
+    def initialize(if_, then_, else_, depth: 1)
+      @if = if_
+      @then = then_
+      @else = else_
+      @depth = depth
+    end
+
+    def type
+      TYPES[:any]
+    end
+
+    def ==(other)
+      other.is_a?(Condition) && @if == other.if && @then == other.then && @else == other.else
+    end
+  end
+end

data/lib/cel/ast/elements/duration.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Cel
+  class Duration < Literal
+    def initialize(value)
+      value =
+        case value
+        when ::String
+          init_from_string(value)
+        when Hash
+          seconds, nanos = value.values_at(:seconds, :nanos)
+          seconds ||= 0
+          nanos ||= 0
+          seconds + (nanos / 1_000_000_000.0)
+        else
+          value
+        end
+
+      raise EvaluateError, "out of range" unless (value * 1_000_000_000).between?(-MAX_INT, MAX_INT)
+
+      super(:duration, value)
+    end
+
+    def to_s
+      seconds = getSeconds
+      millis = getMilliseconds
+      millis.positive? ? "#{seconds}s#{millis}m" : "#{seconds}s"
+    end
+
+    define_cel_method(:+) do |other|
+      case other
+      when Cel::Duration
+        Cel::Duration.new(@value + other.value)
+      when Cel::Timestamp
+        Cel::Timestamp.new(other.value + @value)
+      end
+    end
+
+    define_cel_method(:-) do |other|
+      case other
+      when Cel::Duration
+        Cel::Duration.new(@value - other.value)
+      else
+        raise Error, "invalid operand #{other} for `-`"
+      end
+    end
+
+    LOGICAL_OPERATORS.each do |op|
+      class_eval(<<-OUT, __FILE__, __LINE__ + 1)
+        define_cel_method(:#{op}) do |other|
+          case other
+          when Cel::Literal
+            Bool.cast(super(other))
+          when Numeric
+            @value == other
+
+          else
+            super(other)
+          end
+        end
+      OUT
+    end
+
+    # Cel Functions
+
+    define_cel_method(:getHours) do
+      Cel::Number.new(:int, (getMinutes / 60).to_i)
+    end
+
+    define_cel_method(:getMinutes) do
+      Cel::Number.new(:int, (getSeconds / 60).to_i)
+    end
+
+    define_cel_method(:getSeconds) do
+      Cel::Number.new(:int, @value.divmod(1).first)
+    end
+
+    define_cel_method(:getMilliseconds) do
+      Cel::Number.new(:int, (@value.divmod(1).last * 1000).round)
+    end
+
+    def to_ruby_type
+      Protobuf.duration_class.new(seconds: getSeconds.value, nanos: getMilliseconds.value * 1_000_000_000.0)
+    end
+
+    private
+
+    def init_from_string(value)
+      seconds = 0
+      nanos = 0
+      value.scan(/([0-9]*(?:\.[0-9]*)?)([a-z]+)/) do |duration, units|
+        case units
+        when "h"
+          seconds += Cel.to_numeric(duration) * 60 * 60
+        when "m"
+          seconds += Cel.to_numeric(duration) * 60
+        when "s"
+          seconds += Cel.to_numeric(duration)
+        when "ms"
+          nanos += Cel.to_numeric(duration) * 1000 * 1000
+        when "us"
+          nanos += Cel.to_numeric(duration) * 1000
+        when "ns"
+          nanos += Cel.to_numeric(duration)
+        else
+          raise EvaluateError, "#{units} is unsupported"
+        end
+      end
+      duration = seconds + (nanos / 1_000_000_000.0)
+      duration = -duration if value.start_with?("-")
+      duration
+    end
+  end
+end

data/lib/cel/ast/elements/function.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Cel
+  class Function
+    attr_reader :label, :types, :type
+
+    def initialize(*types, label: nil, return_type: nil, &func)
+      unless func.nil?
+        types = Array.new(func.arity) { TYPES[:any] } if types.empty?
+        raise(Error, "number of arg types does not match number of yielded args") unless types.size == func.arity
+      end
+      @types = types.map { |typ| typ.is_a?(Type) ? typ : TYPES[typ] }
+      @type = if return_type.nil?
+        TYPES[:any]
+      else
+        return_type.is_a?(Type) ? return_type : TYPES[return_type]
+      end
+      @func = func
+      @label = label
+    end
+
+    def call(*args)
+      result = @func.call(*args)
+
+      @type.convert(result)
+    end
+  end
+
+  mod = self
+  mod.define_singleton_method(:Function) do |*args, **kwargs, &blk|
+    mod::Function.new(*args, **kwargs, &blk)
+  end
+end

data/lib/cel/ast/elements/group.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Cel
+  class Group
+    attr_reader :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def type
+      TYPES[:any]
+    end
+
+    def ==(other)
+      other.is_a?(Group) && @value == other.value
+    end
+  end
+end

data/lib/cel/ast/elements/identifier.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Cel
+  class Identifier < SimpleDelegator
+    attr_reader :id
+
+    attr_accessor :type
+
+    def initialize(identifier, package = nil)
+      @id = identifier
+      @type = TYPES[:any]
+      @package = package
+      super(@id)
+    end
+
+    def ==(other)
+      super || other.to_s == @id.to_s
+    end
+
+    def to_s
+      @id.to_s
+    end
+
+    alias_method :to_ruby_type, :to_s
+
+    def try_convert_to_proto_type
+      Protobuf.convert_to_proto_type(@id.to_s, @package)
+    end
+  end
+end

data/lib/cel/ast/elements/invoke.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Cel
+  class Invoke
+    attr_accessor :var
+
+    attr_reader :func, :args, :depth
+
+    def self.new(func:, var: nil, args: nil, **rest)
+      Protobuf.try_invoke_from(var, func, args) || super
+    end
+
+    def type
+      TYPES[:any]
+    end
+
+    def initialize(func:, var: nil, args: nil, depth: 1, package: nil)
+      @var = var
+      @func = func.to_sym
+      @args = args
+      @package = package
+      @depth = depth
+    end
+
+    def ==(other)
+      case other
+      when Invoke
+        @var == other.var && @func == other.func && @args == other.args
+      when Array
+        [@var, @func, @args].compact == other
+      else
+        super
+      end
+    end
+
+    def to_s
+      if var
+        if indexing?
+          "#{var}[#{args}]"
+        else
+          "#{var}.#{func}#{"(#{args.map(&:to_s).join(", ")})" if args}"
+        end
+      else
+        "#{func}#{"(#{args.map(&:to_s).join(", ")})" if args}"
+      end
+    end
+
+    def try_convert_to_proto_type
+      return unless @var
+
+      proto_type = Protobuf.convert_to_proto_type(@var.to_s, @package)
+
+      return unless proto_type
+
+      return proto_type unless proto_type.const_defined?(@func)
+
+      proto_type.const_get(@func)
+    end
+
+    def indexing?
+      @func == :[]
+    end
+  end
+end

data/lib/cel/ast/elements/list.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Cel
+  class List < Literal
+    attr_reader :depth
+
+    def initialize(value, depth: 1)
+      value = value.map do |v|
+        Literal.to_cel_type(v)
+      end
+      super(TYPES[:list], value)
+      @depth = depth
+    end
+
+    define_cel_method(:[]) do |key|
+      case key
+      when Number
+        if key.type == :double
+          val = key.value
+
+          raise InvalidArgumentError, key unless (val % 1).zero?
+        end
+      end
+
+      super(key)
+    end
+
+    def to_ary
+      [self]
+    end
+
+    def to_ruby_type
+      value.map(&:to_ruby_type)
+    end
+
+    %i[+ -].each do |op|
+      class_eval(<<-OUT, __FILE__, __LINE__ + 1)
+        define_cel_method(:#{op}) do |other|
+          List.new(@value.send(__method__, other.value))
+        end
+      OUT
+    end
+
+    def by_max_depth
+      max = @value.max { |a1, a2| calc_depth(a1, 0) <=> calc_depth(a2, 0) }
+
+      # return the last value if all options have the same depth
+      return @value.last if (max == @value.first) && (calc_depth(max, 0) == calc_depth(@value.last, 0))
+
+      max
+    end
+
+    def to_s
+      "[#{@value.map(&:to_s).join(", ")}]"
+    end
+
+    private
+
+    def calc_depth(element, acc)
+      case element
+      when List
+        element.value.map { |el| calc_depth(el, acc + 1) }.max || (acc + 1)
+      when Map
+        element.value.map { |(_, el)| calc_depth(el, acc + 1) }.max || (acc + 1)
+      else
+        acc
+      end
+    end
+  end
+end

data/lib/cel/ast/elements/literal.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Cel
+  class Literal < SimpleDelegator
+    include CelMethods
+
+    attr_reader :type, :value
+
+    class << self
+      def to_cel_type(val)
+        if val.is_a?(Protobuf.base_class) ||
+           val.is_a?(Struct) # no-protobuf mode
+          val = Protobuf.try_convert_from_wrapper(val)
+
+          return val if val.is_a?(Protobuf.base_class) # still
+        end
+
+        case val
+        when Literal, Identifier, Invoke, Operation, Condition, Group, # already cel
+            Protobuf.enum_class # already a usable class a la protobuf
+          val
+        when Protobuf.map_class
+          Map.new(val.to_h)
+        when ::String
+          String.new(val)
+        when ::Symbol
+          Identifier.new(val)
+        when ::Integer
+          Number.new(:int, val)
+        when ::Float, ::BigDecimal
+          Number.new(:double, val)
+        when ::Hash
+          Map.new(val)
+        when ::Array
+          List.new(val)
+        when true, false
+          Bool.cast(val)
+        when nil
+          Null::INSTANCE
+        when Time
+          Timestamp.new(val)
+        else
+          raise BindingError, "can't convert #{val} to CEL type"
+        end
+      end
+    end
+
+    def initialize(type, value)
+      @type = type.is_a?(Type) ? type : TYPES[type]
+      @value = value
+      super(value)
+      check
+    end
+
+    define_cel_method(:==) do |other|
+      case other
+      when Literal
+        @type == other.type && @value == other.value
+      else
+        @value == other
+      end
+    end
+
+    define_cel_method(:"!=") do |other|
+      !cel_send(:==, other)
+    end
+
+    private
+
+    def check; end
+
+    alias_method :to_ruby_type, :value
+  end
+end