cel 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12cebd55174d05db4f154e185872921949f3931817503fccb5dec9f516c3128d
-  data.tar.gz: 8fa9c386f343ecfdda97ce99c37296e15378763ab0308270fdc0e789cb4c9ab0
+  metadata.gz: 5e83a98ac5e076442ae06b53d13f43581a3982196f57582bbac02a08eef46ca9
+  data.tar.gz: 1fdb06029d13f3a47037688df7d4d4a77f65e237aa73d0e00fb6989a78600000
 SHA512:
-  metadata.gz: a46166c14750ef4fc245d1aca362f103d4340ddce4155c51e2f49e03ea64c5d812dccaf61ac073f9f6207995a2f8090a748fe06bf984159542385416a2e9e83a
-  data.tar.gz: cfa9d65dd070389fca1ed80817a83baee1efe193cab6830bfd0a3278051a8593a673a4de8e19c19db1a450312cad69ccb91ac49e5db2ee02d18d0efb301319c1
+  metadata.gz: 59eb650749f3b0fcef9a8ee66b6850831db66f116d851f35894d375191e280cac465e48c1f39103d6fcb21f7ebcf6c695f2cd286c65bcfb6c12ef08ddcb07400
+  data.tar.gz: b6dada73b82d27a17a6d9f23a672f36ec7c9af6f89eebef788227aba7b22cdc88720100ffcf5f466db70e923db689ff4df903942abb7ab2f8adeef70de4604df

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 ## [Unreleased]
 
+## [0.5.0] - 2025-12-11
+
+### Features
+
+#### Custom extensions
+
+A new `:extensions` kwarg is added to `Cel::Environment.new` which allows adding custom extensions, in a similar manner as what the standard extensions (like `math` or `string`) are done:
+
+```ruby
+module Ext
+  # defines a random function which takes no arguments and returns 42
+end
+
+Cel::Environment.new.evaluate("ext.random()") #=> raises error
+Cel::Environment.new(extensions: { ext: Ext }).evaluate("ext.random()") #=> 42
+```
+
+### Backwards Compatibility
+
+The ractor safety introduced in 0.4.1 has been relaxed in order to allow extensions of core classes by custom extensions, And you'll need to explicitly call `Cel.freeze` before using `cel` inside ractors. This is a direct consequence of how extensions patch `cel` core classes.
+
+ATTENTION: Changes may be introduced in the way core classes are patched by extensions, towards making `cel` ractor-safe by default. If you rely on custom extensions, do follow the migration instructions in subsequent releases.
+
+### Bugfixes
+
+Fixed checker type inference when using nexted expressions (like when using the `bind` extensions to evaluate cel sub-expressions).
+
+## [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
@@ -23,7 +67,7 @@ When the `tzinfo-data` gem is loaded, expressions will support human-friendly ti
 
 ### Bugfixes
 
-* `has()` macro correctly works for mapsl
+* `has()` macro correctly works for maps
 
 ## [0.3.0] - 2025-06-12
 

data/README.md

@@ -139,6 +139,58 @@ 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]
+```
+
+### Custom Extensions
+
+`cel` already supports the [conformance spec extensions packages](https://pkg.go.dev/github.com/google/cel-go/ext#section-readme). However, if you need to add your own, you can do so:
+
+```ruby
+module Ext
+  def __check(funcall, checker:)
+    func = funcall.func
+    args = funcall.args
+
+    case func
+    when :random
+      checker.check_arity(func, args, 0)
+      return TYPES[:int]
+    else
+      checker.unsupported_operation(funcall)
+    end
+  end
+
+  # extensions will always receive the program instance as a kwarg
+  def random(program:)
+    42
+  end
+end
+
+env = Cel::Environment.new(extensions: { ext: Ext})
+env.evaluate("ext.random()") #=> 42
+```
+
 ## 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:
@@ -157,6 +209,14 @@ If this is something you're interested in (helping out), add a mention in the co
 
 All Rubies greater or equal to 2.7, and always latest JRuby and Truffleruby.
 
+`cel` can be used inside ractors, but you need to freeze it first:
+
+```ruby
+# can't be used in ractors
+Cel.freeze
+# can be used in ractors
+```
+
 ## Development
 
 Clone the repo in your local machine, where you have `ruby` installed. Then you can:
@@ -185,7 +245,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