cel 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcb8e069501a6c9cfdf6af67f83701111d67130d04a9208a05482d14ac1c519a
-  data.tar.gz: 0af115f5924dd63f926227fd916c2fe3f2b25bb6a68e682df1c9f5be36b1be6f
+  metadata.gz: 12cebd55174d05db4f154e185872921949f3931817503fccb5dec9f516c3128d
+  data.tar.gz: 8fa9c386f343ecfdda97ce99c37296e15378763ab0308270fdc0e789cb4c9ab0
 SHA512:
-  metadata.gz: d78064a96c11a026f1b6f16a3ebdfed6f3f528170975ab9c26b1e7438c7805419830418f32e7b6557bafeace936c35f1dc18f695a1294862780c2aff9e0bc335
-  data.tar.gz: 9897a6ed3a7708cefaf1b6bd24f86802b1c50709cbbb9bab1fd843e31e3dc1f1f049f4770afa0c34ed89c91b30442a95738b30eb52d91e64d99f1dbc880e0de9
+  metadata.gz: a46166c14750ef4fc245d1aca362f103d4340ddce4155c51e2f49e03ea64c5d812dccaf61ac073f9f6207995a2f8090a748fe06bf984159542385416a2e9e83a
+  data.tar.gz: cfa9d65dd070389fca1ed80817a83baee1efe193cab6830bfd0a3278051a8593a673a4de8e19c19db1a450312cad69ccb91ac49e5db2ee02d18d0efb301319c1

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 ## [Unreleased]
 
+## [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
+
+* Support for depth protection, using the defaults from the spec (ex: recursion depth of 32, nesting depth of 32), and supporting API to override them (ex: `Cel::Environment.new(max_recursion_depth: 42))`).
+* lazy-evaluating bindings to avoid upfront costly transformations of ruby objects into cel objects which are ultimately not used in expressions.
+
+### Bugfixes
+
+* `has()` macro correctly works for mapsl
+
 ## [0.3.0] - 2025-06-12
 
 ### Features

data/README.md

@@ -32,7 +32,7 @@ The usage pattern follows the pattern defined by [cel-go](https://github.com/goo
 require "cel"
 
 # set the environment
-env = Cel::Environment.new(name: :string, group: :string)
+env = Cel::Environment.new(declarations: { name: :string, group: :string })
 
 # 1.1 parse
 begin
@@ -67,20 +67,52 @@ end
 puts return_value #=> true
 ```
 
-### types
+### Environment
 
-`cel-ruby` supports declaring the types of variables in the environment, which allows for expression checking:
+`Cel::Environment` is the entrypoint for parsing, checking and evaluating CEL expressions, as well as customizing/constraining any of these functions. For that matter, it can be initialized with the following keyword arguments:
+
+* `:declarations`: a hash of the expected variables names-to-cel-types, which are used to validate the expression and data bindings. When variables aren't declared, they assume the `any` type.
+* `:container`: used to declare the package of protobuf messages only declared by name used in the expression (i.e. `cel.expr.conformance.proto3`).
+* `:disable_check`: (defaults to `false`) enables/disables expression check phase (except when `env.check(expr)` is explicitly called).
+* `max_recursion_depth`: (defaults to `32`) max number of parsable recursive/repeating rules, as per what the spec states.
+* `max_nesting_depth`: (defaults to `12`) max number of parsable nested rules, as per what the spec states.
+
+#### declarations
+
+`cel-ruby` supports declaring the types of variables in the environment, which enhances expression type checking:
 
 ```ruby
+# without declarations
+env = Cel::Environment.new
+env.check("[first_name] + middle_names + [last_name]") #=> any
+
+# with declarations
 env = Cel::Environment.new(
-  first_name: :string, # shortcut for Cel::Types[:string]
-  middle_names: Cel::Types[:list, :string], # list of strings
-  last_name: :string
+  declarations: {
+    first_name: :string, # shortcut for Cel::Types[:string]
+    middle_names: Cel::TYPES[:list, :string], # list of strings
+    last_name: :string
+  }
 )
+env.check("[first_name] + middle_names + [last_name]") #=> list(string)
+
+# you can use Cel::TYPES to access any type of primitive type, i.e. Cel::TYPES[:bytes]
+```
+
+#### :container
+
+This can be used to simplify writing CEL expressions with long protobuf package declarations:
 
-# you can use Cel::Types to access any type of primitive type, i.e. Cel::Types[:bytes]
+```ruby
+env = Cel::Environment.new
+env.evaluate("my.company.private.protobufs.Account{id: 2}.id)")
+# or
+env = Cel::Environment.new(container: "my.company.private.protobufs.")
+env.evaluate("Account{id: 2}.id)")
 ```
 
+**Note**: the `google.protobuf` packaged is already supported OOTB.
+
 ### protobuf
 
 If `google/protobuf` is available in the environment, `cel-ruby` will also be able to integrate with protobuf declarations in CEL expressions.
@@ -99,11 +131,11 @@ 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
 ```
 

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

@@ -8,6 +8,25 @@ require "google/protobuf/well_known_types"
 
 module Cel
   module Protobuf
+    PROTOBUF_VALUES = Set.new(
+      ["Any", "google.protobuf.Any",
+       "ListValue", "google.protobuf.ListValue",
+       "Struct", "google.protobuf.Struct",
+       "Value", "google.protobuf.Value",
+       "BoolValue", "google.protobuf.BoolValue",
+       "BytesValue", "google.protobuf.BytesValue",
+       "DoubleValue", "google.protobuf.DoubleValue",
+       "FloatValue", "google.protobuf.FloatValue",
+       "Int32Value", "google.protobuf.Int32Value",
+       "Int64Value", "google.protobuf.Int64Value",
+       "Uint32Value", "google.protobuf.Uint32Value",
+       "Uint64Value", "google.protobuf.Uint64Value",
+       "NullValue", "google.protobuf.NullValue",
+       "StringValue", "google.protobuf.StringValue",
+       "Timestamp", "google.protobuf.Timestamp",
+       "Duration", "google.protobuf.Duration"]
+    )
+
     module_function
 
     def base_class
@@ -294,34 +313,18 @@ module Cel
     end
 
     def try_invoke_from(var, func, args)
-      case var
-      when "Any", "google.protobuf.Any",
-        "ListValue", "google.protobuf.ListValue",
-        "Struct", "google.protobuf.Struct",
-        "Value", "google.protobuf.Value",
-        "BoolValue", "google.protobuf.BoolValue",
-        "BytesValue", "google.protobuf.BytesValue",
-        "DoubleValue", "google.protobuf.DoubleValue",
-        "FloatValue", "google.protobuf.FloatValue",
-        "Int32Value", "google.protobuf.Int32Value",
-        "Int64Value", "google.protobuf.Int64Value",
-        "Uint32Value", "google.protobuf.Uint32Value",
-        "Uint64Value", "google.protobuf.Uint64Value",
-        "NullValue", "google.protobuf.NullValue",
-        "StringValue", "google.protobuf.StringValue",
-        "Timestamp", "google.protobuf.Timestamp",
-        "Duration", "google.protobuf.Duration"
-        protoclass = var.split(".").last
-        protoclass = Google::Protobuf.const_get(protoclass)
-
-        value = if args.nil? && protoclass.constants.include?(func.to_sym)
-          protoclass.const_get(func)
-        else
-          protoclass.__send__(func, *args)
-        end
+      return unless var.respond_to?(:to_str) && PROTOBUF_VALUES.include?(var.to_str)
 
-        Literal.to_cel_type(value)
+      protoclass = var.split(".").last
+      protoclass = Google::Protobuf.const_get(protoclass)
+
+      value = if args.nil? && protoclass.constants.include?(func.to_sym)
+        protoclass.const_get(func)
+      else
+        protoclass.__send__(func, *args)
       end
+
+      Literal.to_cel_type(value)
     end
 
     # finds value for +attribute+ declared in the +proto+.

data/lib/cel/ast/elements.rb

@@ -37,12 +37,13 @@ module Cel
   class Message
     EMPTY_STRUCT = {}.freeze
 
-    attr_reader :name, :struct, :package
+    attr_reader :name, :struct, :package, :depth
 
-    def initialize(name, struct, package: nil)
+    def initialize(name, struct, package: nil, depth: 1)
       @struct = struct ? struct.transform_keys(&:to_sym) : EMPTY_STRUCT
       @name = name
       @package = package
+      @depth = depth
     end
 
     def type
@@ -83,7 +84,7 @@ module Cel
   class Invoke
     attr_accessor :var
 
-    attr_reader :func, :args
+    attr_reader :func, :args, :depth
 
     def self.new(func:, var: nil, args: nil, **rest)
       Protobuf.try_invoke_from(var, func, args) || super
@@ -93,11 +94,12 @@ module Cel
       TYPES[:any]
     end
 
-    def initialize(func:, var: nil, args: nil, package: nil)
+    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)
@@ -113,7 +115,7 @@ module Cel
 
     def to_s
       if var
-        if func == :[]
+        if indexing?
           "#{var}[#{args}]"
         else
           "#{var}.#{func}#{"(#{args.map(&:to_s).join(", ")})" if args}"
@@ -134,6 +136,10 @@ module Cel
 
       proto_type.const_get(@func)
     end
+
+    def indexing?
+      @func == :[]
+    end
   end
 
   class Function
@@ -266,7 +272,7 @@ module Cel
     %i[+ -].each do |op|
       class_eval(<<-OUT, __FILE__, __LINE__ + 1)
         def #{op}@
-          raise EvaluateError, "no such overload" if @type == TYPES[:uint]
+          raise NoOverloadError if @type == TYPES[:uint]
           value = super
           Number.new(@type, value)
         end
@@ -358,6 +364,10 @@ module Cel
         end
       OUT
     end
+
+    def to_s
+      inspect
+    end
   end
 
   class Bytes < Literal
@@ -392,11 +402,14 @@ module Cel
   end
 
   class List < Literal
-    def initialize(value)
+    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
 
     def [](key)
@@ -429,22 +442,26 @@ module Cel
     end
 
     def by_max_depth
-      max = @value.max { |a1, a2| depth(a1, 0) <=> depth(a2, 0) }
+      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) && (depth(max, 0) == depth(@value.last, 0))
+      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 depth(element, acc)
+    def calc_depth(element, acc)
       case element
       when List
-        element.value.map { |el| depth(el, acc + 1) }.max || (acc + 1)
+        element.value.map { |el| calc_depth(el, acc + 1) }.max || (acc + 1)
       when Map
-        element.value.map { |(_, el)| depth(el, acc + 1) }.max || (acc + 1)
+        element.value.map { |(_, el)| calc_depth(el, acc + 1) }.max || (acc + 1)
       else
         acc
       end
@@ -453,13 +470,16 @@ module Cel
 
   class Map < Literal
     ALLOWED_TYPES = %i[int uint bool string].map { |typ| TYPES[typ] }.freeze
-    def initialize(value)
+
+    attr_reader :depth
+
+    def initialize(value, depth: 1)
       # store array internally to support repeated keys
       value = value.map do |k, v|
         [Literal.to_cel_type(k), Literal.to_cel_type(v)]
       end
       super(TYPES[:map], value)
-      check
+      @depth = depth
     end
 
     def ==(other)
@@ -507,13 +527,19 @@ module Cel
     end
 
     def respond_to_missing?(meth, *args)
-      super || (@value && @value.any? { |k, _| k.to_s == meth.to_s })
+      return true if super
+      return false unless @value
+
+      meth_s = meth.to_s
+
+      @value.any? { |k, _| k == meth_s }
     end
 
     def method_missing(meth, *args)
       return super unless @value
 
-      values = @value.filter_map { |k, v| v if k.to_s == meth.to_s }
+      meth_s = meth.to_s
+      values = @value.filter_map { |k, v| v if k == meth_s }
 
       return super if values.empty?
 
@@ -615,6 +641,10 @@ module Cel
       Protobuf.timestamp_class.from_time(@value)
     end
 
+    def to_s
+      @value.utc.iso8601
+    end
+
     private
 
     def to_local_time(tz = nil)
@@ -760,14 +790,15 @@ module Cel
   end
 
   class Operation
-    attr_reader :op, :operands
+    attr_reader :op, :operands, :depth
 
     attr_accessor :type
 
-    def initialize(op, operands)
+    def initialize(op, operands, depth: 1)
       @op = op
       @operands = operands
       @type = TYPES[:any]
+      @depth = depth
     end
 
     def ==(other)
@@ -795,12 +826,13 @@ module Cel
   end
 
   class Condition
-    attr_reader :if, :then, :else
+    attr_reader :if, :then, :else, :depth
 
-    def initialize(if_, then_, else_)
+    def initialize(if_, then_, else_, depth: 1)
       @if = if_
       @then = then_
       @else = else_
+      @depth = depth
     end
 
     def type

data/lib/cel/ast/types.rb

@@ -176,7 +176,7 @@ module Cel
     end
 
     def cast(value)
-      List.new(value)
+      value.is_a?(List) ? value : List.new(value)
     end
   end
 
@@ -203,7 +203,7 @@ module Cel
     end
 
     def cast(value)
-      Map.new(value)
+      value.is_a?(Map) ? value : Map.new(value)
     end
   end
 

data/lib/cel/checker.rb

@@ -21,7 +21,7 @@ module Cel
       timestamp: %i[int string timestamp],
     }.freeze
 
-    attr_reader :declarations
+    attr_reader :environment, :declarations
 
     def initialize(environment, declarations = environment.declarations)
       @environment = environment
@@ -51,6 +51,40 @@ module Cel
 
     alias_method :call, :check
 
+    def find_match_all_types(expected, types)
+      # at least an expected type must match all values
+      type = expected.find do |expected_type|
+        case types
+        when Array
+          types.all? { |typ| typ == expected_type }
+        else
+          types == expected_type
+        end
+      end
+
+      type && types.is_a?(Type) ? types : TYPES[type]
+    end
+
+    def check_arity(func, args, arity, op = :===)
+      return if arity.__send__(op, args.size)
+
+      raise CheckError, "`#{func}` invoked with wrong number of arguments (should be #{arity})"
+    end
+
+    def check_arity_any(func, args)
+      return if args.size.positive?
+
+      raise CheckError, "`#{func}` invoked with no arguments"
+    end
+
+    def unsupported_type(op)
+      raise CheckError, "no matching overload: #{op}"
+    end
+
+    def unsupported_operation(op)
+      raise CheckError, "unsupported operation (#{op})"
+    end
+
     private
 
     def merge(declarations)
@@ -194,6 +228,10 @@ module Cel
 
       return check_standard_func(funcall) unless var
 
+      if var.is_a?(Identifier) && Cel::EXTENSIONS.include?(var.to_sym)
+        return Cel::EXTENSIONS[var.to_sym].__check(funcall, checker: self)
+      end
+
       var_type ||= infer_variable_type(var)
 
       case var_type
@@ -283,6 +321,8 @@ module Cel
           var_type.element_type = element_checker.check(predicate)
           var_type
         else
+          return Cel::EXTENSIONS[:strings].__check(funcall, checker: self) if Cel::EXTENSIONS.key?(:strings)
+
           unsupported_operation(funcall)
         end
       when TYPES[:string]
@@ -295,6 +335,8 @@ module Cel
           # TODO: verify if string can be transformed into a regex
           return TYPES[:bool] if find_match_all_types(%i[string], call(args.first))
         else
+          return Cel::EXTENSIONS[:strings].__check(funcall, checker: self) if Cel::EXTENSIONS.key?(:strings)
+
           unsupported_type(funcall)
         end
         unsupported_operation(funcall)
@@ -373,7 +415,7 @@ module Cel
 
         arg = call(args.first)
 
-        return TYPES[func] if find_match_all_types(allowed_types, arg)
+        return TYPES[func] if find_match_all_types(allowed_types, arg) || arg == TYPES[:any]
       when :matches
         check_arity(func, args, 2)
         return TYPES[:bool] if find_match_all_types(%i[string], args.map(&method(:call)))
@@ -424,7 +466,9 @@ module Cel
     def check_identifier(identifier)
       return identifier.type unless identifier.type == :any
 
-      return TYPES[:type] if Cel::PRIMITIVE_TYPES.include?(identifier.to_sym)
+      id_sym = identifier.to_sym
+
+      return TYPES[:type] if Cel::PRIMITIVE_TYPES.include?(id_sym)
 
       proto_type = identifier.try_convert_to_proto_type
 
@@ -472,33 +516,5 @@ module Cel
         typ
       end
     end
-
-    def find_match_all_types(expected, types)
-      # at least an expected type must match all values
-      type = expected.find do |expected_type|
-        case types
-        when Array
-          types.all? { |typ| typ == expected_type }
-        else
-          types == expected_type
-        end
-      end
-
-      type && types.is_a?(Type) ? types : TYPES[type]
-    end
-
-    def check_arity(func, args, arity)
-      return if arity === args.size # rubocop:disable Style/CaseEquality
-
-      raise CheckError, "`#{func}` invoked with wrong number of arguments (should be #{arity})"
-    end
-
-    def unsupported_type(op)
-      raise CheckError, "no matching overload: #{op}"
-    end
-
-    def unsupported_operation(op)
-      raise CheckError, "unsupported operation (#{op})"
-    end
   end
 end

data/lib/cel/context.rb

@@ -2,28 +2,11 @@
 
 module Cel
   class Context
-    attr_reader :declarations
+    attr_reader :declarations, :bindings
 
     def initialize(declarations, bindings)
       @declarations = declarations
       @bindings = bindings.dup
-
-      return unless @bindings
-
-      @bindings.each do |k, v|
-        if @declarations && (type = @declarations[k])
-          type = TYPES[type] if type.is_a?(Symbol)
-
-          val = if type.is_a?(Class) && type < Protobuf.base_class
-            Protobuf.convert_to_proto(type, v)
-          else
-            type.cast(to_cel_type(v))
-          end
-        else
-          val = to_cel_type(v)
-        end
-        @bindings[k] = val
-      end
     end
 
     def lookup(identifier)
@@ -39,6 +22,7 @@ module Cel
         fetched = false
         (0...lookup_keys.size).reverse_each do |idx|
           key = lookup_keys[0..idx].join(".").to_sym
+          is_binding = val == @bindings
 
           val = if val.respond_to?(:key?)
             # hash
@@ -56,7 +40,8 @@ module Cel
             end
           end
 
-          lookup_keys = lookup_keys[idx + 1..]
+          val = @bindings[key] = to_cel_primitive(key, val) if is_binding
+          lookup_keys = lookup_keys[(idx + 1)..]
           fetched = true
           break
         end
@@ -86,5 +71,19 @@ module Cel
     def to_cel_type(v)
       Literal.to_cel_type(v)
     end
+
+    def to_cel_primitive(k, v)
+      if @declarations && (type = @declarations[k])
+        type = TYPES[type] if type.is_a?(Symbol)
+
+        if type.is_a?(Class) && type < Protobuf.base_class
+          Protobuf.convert_to_proto(type, v)
+        else
+          type.cast(to_cel_type(v))
+        end
+      else
+        to_cel_type(v)
+      end
+    end
   end
 end

data/lib/cel/environment.rb

@@ -4,7 +4,12 @@ module Cel
   class Environment
     attr_reader :declarations, :package
 
-    def initialize(declarations: nil, container: nil, disable_check: false)
+    def initialize(
+      declarations: nil,
+      container: nil,
+      disable_check: false,
+      **kwargs
+    )
       @disable_check = disable_check
       @declarations = declarations
       @container = container
@@ -28,7 +33,7 @@ module Cel
         @package = Object.const_get(proto_module_name) if Object.const_defined?(proto_module_name)
       end
 
-      @parser = Parser.new(package)
+      @parser = Parser.new(package, **kwargs)
     end
 
     def compile(expr)
@@ -48,8 +53,8 @@ module Cel
     end
 
     def check(expr)
-      ast = @parser.parse(expr)
-      @checker.check(ast)
+      expr = @parser.parse(expr) if expr.is_a?(::String)
+      @checker.check(expr)
     end
 
     def program(expr)
@@ -86,6 +91,19 @@ module Cel
       [declarations, bindings]
     end
 
+    def with(declarations:, disable_check: @disable_check)
+      prev_declarations = @declarations
+      prev_disable_check = @disable_check
+
+      @declarations = declarations.merge(declarations)
+      @disable_check = disable_check
+
+      yield
+    ensure
+      @declarations = prev_declarations
+      @disable_check = prev_disable_check
+    end
+
     private
 
     def validate(ast, structs); end