arel-extensions 8.1.0 → 9.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26af903829c4fe9d8b881fcd316d09a03f9253af796ab813523d6c074e7fc3fe
-  data.tar.gz: 4c8ff81dc39a82b8dabd1fe792b18c43e9d683bc5f8ede192932fda4d0864667
+  metadata.gz: 99efadd34c12e304c5204c9dc2717bad533bfb20c9c280a036a8abc3110ab34a
+  data.tar.gz: 66c064d703b2531c7676e3a91bef9f0dd813355e24108c7966770ea1fba298ff
 SHA512:
-  metadata.gz: 9a596cde6baa6b9b54fe900786dd63980da37bbe10408ca09ed9bf7a1df3ddb23de11d79e64f75634120e93e134dd739f36872131e13cba2fc1bb90eaa064deb
-  data.tar.gz: 53b6e4cd418d977fb825e1f9753b117bf5b64644dc29be64c530f9f15f44f158aa16f4dc0acd0a39a78eea7856ebf0ec27aa3b65cb7f5b83e09c9e93398e899d
+  metadata.gz: 043be028082fea8d31c8b427db8a703b7f4a2f1916879e77455f05847086964840b4cae0886e73930ace056dc9e86bcb7c375c4794a64f5ac5a85c19d5f9b61b
+  data.tar.gz: 89d8e35f5503774cc499c93fa0cc9ea427dec2cecc27cd6ee01f5d52f9f66f9c278078c80c865d7fc4bac8362e9c860f7fe33b1a90b572c4823621cfe6be9ba3

data/CHANGELOG.md

@@ -0,0 +1,64 @@
+## [9.0.1] - 2026-08-30
+
+### Security
+- Fixed a SQL injection in the PostgreSQL visitor's JSON path handling
+  ([GHSA-75hc-9q9v-9cv2], CWE-89, high). `key`/`dig` path segments were
+  interpolated straight into a `#>'{...}'` array literal, so a segment
+  containing `}'` could close the literal and have the rest of it executed as
+  SQL. Most reachable through activerecord-filter, where a filter key like
+  `"metadata.<payload>"` on a json/jsonb column puts request input into `dig`.
+  Segments are now emitted as a quoted `#> array[...]`, which PostgreSQL folds
+  back to the same `text[]` constant (existing expression indexes still match).
+  Reported by [@saidM](https://github.com/saidM).
+- `cast_as` now validates the type name and raises `ArgumentError` unless it
+  looks like a type identifier. Not reachable from activerecord-filter, but it
+  was the same class of raw interpolation.
+
+### Changed
+- A path segment is now always a single segment: `key('a,b')` emits
+  `array['a,b']`, where the old raw `'{a,b}'` literal let PostgreSQL split it
+  on the comma into two segments. Use `dig('a', 'b')` for multi-segment paths.
+
+[GHSA-75hc-9q9v-9cv2]: https://github.com/malomalo/arel-extensions/security/advisories/GHSA-75hc-9q9v-9cv2
+
+## [9.0.0] - 2026-08-27
+
+### Changed
+- Switched to independent Semantic Versioning. Prior releases tracked the Rails
+  major/minor line; the version number no longer maps to a Rails version.
+- Require Ruby >= 3.3.
+- Require ActiveRecord >= 8.0, < 9.0 (dropped support for Rails older than 8.0).
+
+### Added
+- `gem.description` and gemspec `metadata` (source, changelog, MFA-required).
+
+### Packaging
+- Slimmed the published gem to `lib`, `ext`, `LICENSE`, and `README.md`; removed
+  the deprecated `test_files` declaration.
+
+### Documentation
+- Documented the features arel-extensions adds (DISTINCT ON, NULLS ordering,
+  array/JSON predicates, full-text search, GIS, binary values) in the README.
+- Documented that the GIS predicates (`#intersects`, `#within`) require the
+  optional `rgeo` gem unless passed an Arel node.
+
+## Earlier releases
+
+Prior versions tracked the matching Rails release. See the Git tags for details:
+
+- [8.1.0] - 2025-12-22
+- [8.0.0] - 2025-01-27
+- [7.0.1] - 2023-05-31
+- [7.0.0] - 2022-12-07
+- [6.1.0] - 2021-01-14
+- [6.0.0.7] - 2019-11-04
+- [6.0.0.2] - 2019-08-12
+
+[9.0.0]: https://github.com/malomalo/arel-extensions/compare/v8.1.0...master
+[8.1.0]: https://github.com/malomalo/arel-extensions/releases/tag/v8.1.0
+[8.0.0]: https://github.com/malomalo/arel-extensions/releases/tag/v8.0.0
+[7.0.1]: https://github.com/malomalo/arel-extensions/releases/tag/v7.0.1
+[7.0.0]: https://github.com/malomalo/arel-extensions/releases/tag/v7.0.0
+[6.1.0]: https://github.com/malomalo/arel-extensions/releases/tag/v6.1.0
+[6.0.0.7]: https://github.com/malomalo/arel-extensions/releases/tag/v6.0.0.7
+[6.0.0.2]: https://github.com/malomalo/arel-extensions/releases/tag/v6.0.0.2

data/README.md

@@ -18,5 +18,116 @@ Or install it yourself as:
 
 ## Usage
 
-Just `require 'arel-extensions'` and use Arel/ActiveRecord as you normally would!
-arel-extensions extends ActiveRecord's query methods in both Arel and ActiveRecord.
+Just `require 'arel-extensions'` and use `Arel` / `ActiveRecord` as you normally
+would.
+
+It adds the methods and nodes below to `Arel::Attributes::Attribute` and to
+`ActiveRecord` relations. Most operators generate PostgreSQL-specific SQL.
+
+Attribute-level helpers are used through an Arel attribute, e.g.
+`Model.arel_table[:column]`, typically inside `where` or `order`.
+
+## What it adds
+
+### `DISTINCT ON` (ActiveRecord)
+
+Added to relations (and as a class method via `Model.distinct_on`):
+
+```ruby
+User.distinct_on(:email)          # SELECT DISTINCT ON (users.email) ...
+User.distinct_on(:a, :b)          # DISTINCT ON (users.a, users.b)
+```
+
+`uniq_on` is an alias of `distinct_on`.
+
+### Ordering with NULLS FIRST / LAST
+
+```ruby
+col = User.arel_table[:name]
+User.order(col.asc(:nulls_last))    # ... ORDER BY users.name ASC NULLS LAST
+User.order(col.desc(:nulls_first))  # ... ORDER BY users.name DESC NULLS FIRST
+```
+
+A `RANDOM()` ordering node is also provided.
+
+### Array predicates
+
+```ruby
+tags = Post.arel_table[:tags]
+tags.contained_by(other)   # tags <@ other
+tags.excludes(other)       # NOT (tags @> other)
+```
+
+### JSON / JSONB predicates
+
+```ruby
+data = User.arel_table[:data]
+
+# Keys in a Object
+data['name']                # data #> array['name']
+data.key('name')            # data #> array['name']
+data.index('name')          # data #> array['name']
+
+# Integer index in a Array
+data[0]                     # data #> array['0']
+data.key(0)                 # data #> array['0']
+data.index(0)               # data #> array['0']
+
+# Dig and other operators
+data.dig('address', 'zip')  # data #> array['address','zip']
+data.dig('tags', -1)        # data #> array['tags','-1']
+data.has_key('name')        # data ? 'name'
+data.has_keys('a', 'b')     # data ?& array['a','b']
+data.has_any_key('a', 'b')  # data ?| array['a','b']
+```
+
+A segment may be an integer, which PostgreSQL reads as an array index (negative
+counts from the end); out of range yields `NULL`.
+
+Path segments are quoted, so they are safe to build from untrusted input.
+PostgreSQL folds the array back to `'{address,zip}'::text[]`, so expression
+indexes written against the literal form still match.
+
+### Casting
+
+```ruby
+User.arel_table[:id].cast_as('text')            # (users.id)::text
+User.arel_table[:created_at].cast_as('date')    # (users.created_at)::date
+data.dig('age').cast_as('int')                  # (data #> array['age'])::int
+```
+
+A type name can't be quoted or bound, so `cast_as` accepts only something that
+looks like one; optionally schema qualified, with a modifier. For example:
+`text`, `varchar(255)`, `numeric(10,2)`, `timestamp(6) with time zone`,
+`int[]`, `public.geometry`. An `ArgumentError` will be raised otherwise.
+
+### Full-text search
+
+```ruby
+body = Article.arel_table[:body]
+body.ts_query('quick & fox')          # to_tsvector(body) @@ to_tsquery('quick & fox')
+body.ts_query('quick & fox', 'english')
+```
+
+Nodes for `to_tsvector`, `to_tsquery`, `@@` (`TSMatch`), `ts_rank`, and
+`ts_rank_cd` are available for building ranking expressions.
+
+### GIS predicates (optional)
+
+```ruby
+area = Place.arel_table[:area]
+area.intersects(value)   # ST_Intersects(area, value)
+area.within(value)       # ST_Within(area, value)
+```
+
+`value` may be an Arel node, an RGeo geometry, a WKT/WKB string, or a GeoJSON
+hash. Anything other than an Arel node requires the
+[`rgeo`](https://github.com/rgeo/rgeo) gem, so add it to your Gemfile if you use
+these:
+
+    gem 'rgeo'
+
+### Binary values
+
+`BinaryValue` and `HexEncodedBinaryValue` nodes for embedding binary data
+(escaped `bytea` and `\x`-encoded hex, respectively).

data/lib/active_record/query_methods.rb

@@ -5,51 +5,45 @@ require 'active_record/relation'
 require 'active_record/querying'
 require 'active_record/relation/query_methods'
 
-module ActiveRecord::QueryMethods
-  def distinct_on_values
-    @values["distinct_on_values"] || []
-  end
+module ActiveRecord
+  # Prepended onto ActiveRecord::QueryMethods rather than reopening it, so
+  # these methods don't appear in QueryMethods.public_instance_methods(false)
+  # -- which Rails' QueryingMethodsDelegationTest asserts against -- while
+  # relations still respond to them.
+  module DistinctOn
+    def distinct_on_values
+      @values["distinct_on_values"] || []
+    end
 
-  def distinct_on_values=(value)
-    @values["distinct_on_values"] = value
-  end
+    def distinct_on_values=(value)
+      @values["distinct_on_values"] = value
+    end
 
-  def distinct_on(*fields)
-    spawn.distinct_on!(*fields)
-  end
-  alias uniq_on distinct_on
+    def distinct_on(*fields)
+      spawn.distinct_on!(*fields)
+    end
+    alias uniq_on distinct_on
 
-  def distinct_on!(*fields)
-    fields.flatten!
-    self.distinct_on_values = fields.map { |x| x.is_a?(Arel::Attributes::Attribute) ? x : klass.arel_table[x] }
-    self
-  end
-  alias uniq_on! distinct_on!
+    def distinct_on!(*fields)
+      fields.flatten!
+      self.distinct_on_values = fields.map { |x| x.is_a?(Arel::Attributes::Attribute) ? x : klass.arel_table[x] }
+      self
+    end
+    alias uniq_on! distinct_on!
 
-  private
+    private
 
-  if ActiveRecord.version >= "8.1"
-    def build_arel_with_distinct_on(aliases = nil)
-      arel = build_arel_without_distinct_on(aliases)
-      arel.distinct_on(self.distinct_on_values) if !self.distinct_on_values.empty?
-      arel
-    end
-  elsif ActiveRecord.version >= "7.2"
-    def build_arel_with_distinct_on(connection, aliases = nil)
-      arel = build_arel_without_distinct_on(connection, aliases)
-      arel.distinct_on(self.distinct_on_values) if !self.distinct_on_values.empty?
-      arel
-    end
-  else
-    def build_arel_with_distinct_on(aliases = nil)
-      arel = build_arel_without_distinct_on(aliases)
+    # Version-agnostic: forward whatever build_arel receives (its signature
+    # varies across Rails versions) to the original via super, then apply
+    # the accumulated distinct_on values.
+    def build_arel(*args)
+      arel = super
       arel.distinct_on(self.distinct_on_values) if !self.distinct_on_values.empty?
       arel
     end
   end
-  alias_method :build_arel_without_distinct_on, :build_arel
-  alias_method :build_arel, :build_arel_with_distinct_on
 end
 
+ActiveRecord::QueryMethods.prepend(ActiveRecord::DistinctOn)
 ActiveRecord::Querying.delegate :distinct_on, to: :all
-ActiveRecord::Querying.delegate :distinct_on!, to: :all
+ActiveRecord::Querying.delegate :uniq_on, to: :all

data/lib/arel/extensions/version.rb

@@ -2,6 +2,6 @@
 
 module Arel
   module Extensions
-    VERSION = '8.1.0'
+    VERSION = '9.0.1'
   end
 end

data/lib/arel/visitors/postgresql_extensions.rb

@@ -39,24 +39,24 @@ module Arel
         collector
       end
 
-      def visit_Arel_Attributes_Key(o, collector, last_key = true)
-        if o.relation.is_a?(Arel::Attributes::Key)
-          visit_Arel_Attributes_Key(o.relation, collector, false)
-          if last_key
-            collector << o.name.to_s
-            collector << "}'"
-          else
-            collector << o.name.to_s
-            collector << ","
-          end
-        else
-          visit(o.relation, collector)
-          collector << "\#>'{" << o.name.to_s
-          collector << (last_key ? "}'" : ",")
+      # Path segments are emitted as a quoted `array[...]` rather than
+      # interpolated into a `'{...}'` array literal, so a segment can never
+      # break out of the path and inject SQL (GHSA-75hc-9q9v-9cv2). PostgreSQL
+      # const-folds the array back to `'{a,b}'::text[]`, so expression indexes
+      # on the literal form still match.
+      def visit_Arel_Attributes_Key(o, collector)
+        keys = []
+        node = o
+        while node.is_a?(Arel::Attributes::Key)
+          keys.unshift(quote(node.name.to_s))
+          node = node.relation
         end
+
+        visit(node, collector)
+        collector << " #> array[" << keys.join(',') << "]"
         collector
       end
-
+      
       def visit_Arel_Nodes_HasKey(o, collector)
         right = o.right
 
@@ -84,10 +84,24 @@ module Arel
         collector
       end
 
+      # A type name can't be bound or quoted, so only allow something that
+      # actually looks like one -- optionally schema qualified, with a modifier
+      # and/or array suffix. Keeps user input from reaching the SQL as-is.
+      CAST_TYPE = /\A
+        [a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)?  # type, optionally schema qualified
+        (\(\d+(\s*,\s*\d+)?\))?                # "varchar(255)", "numeric(10,2)"
+        (\ [a-z]+)*                            # "timestamp with time zone"
+        (\(\d+(\s*,\s*\d+)?\))?                # "character varying(255)"
+        (\[\])*                                # "int[]"
+      \z/xi
+      
       def visit_Arel_Attributes_Cast(o, collector)
+        type = o.name.to_s
+        raise ArgumentError, "invalid cast type: #{type.inspect}" unless CAST_TYPE.match?(type)
+
         collector << "("
         visit(o.relation, collector)
-        collector << ")::#{o.name}"
+        collector << ")::#{type}"
         collector
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: arel-extensions
 version: !ruby/object:Gem::Version
-  version: 8.1.0
+  version: 9.0.1
 platform: ruby
 authors:
 - Jon Bracy
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: 8.0.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
@@ -25,24 +25,10 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 7.0.0
+        version: 8.0.0
     - - "<"
       - !ruby/object:Gem::Version
         version: '9.0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -169,19 +155,18 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
+description: Extends Arel and ActiveRecord with SQL operators and functions that aren't
+  available out of the box, including array and JSON predicates, PostgreSQL full-text
+  search (tsvector/tsquery), GIS/geometry predicates, and additional ordering helpers.
 email:
 - jonbracy@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".github/workflows/ci.yml"
-- ".gitignore"
-- Gemfile
+- CHANGELOG.md
 - LICENSE
 - README.md
-- Rakefile
-- arel-extensions.gemspec
 - ext/arel/nodes/ascending.rb
 - ext/arel/nodes/descending.rb
 - ext/arel/order_predications.rb
@@ -214,17 +199,13 @@ files:
 - lib/arel/visitors/postgresql_extensions.rb
 - lib/arel/visitors/sunstone_extensions.rb
 - lib/arel/visitors/to_sql_extensions.rb
-- test/binary_value_test.rb
-- test/database.rb
-- test/gis_test.rb
-- test/order_test.rb
-- test/sunstone_test.rb
-- test/test_helper.rb
-- test/ts_test.rb
 homepage: https://github.com/malomalo/arel-extensions
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/malomalo/arel-extensions
+  changelog_uri: https://github.com/malomalo/arel-extensions/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -232,21 +213,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.2
+rubygems_version: 4.0.11
 specification_version: 4
 summary: Adds support for missing SQL operators and functions to Arel
-test_files:
-- test/binary_value_test.rb
-- test/database.rb
-- test/gis_test.rb
-- test/order_test.rb
-- test/sunstone_test.rb
-- test/test_helper.rb
-- test/ts_test.rb
+test_files: []