where: Support String arguments

The problem
---

When a resource queries an "index"-like endpoint and receives a response
payload that relies on URL-based pagination, it can be tedious to
deconstruct the next page's URL and transform it into a subsequent
`.where` call.

For example, consider a `Post` payload like:

```json
{
  "posts": { … },
  "next_page": "https://api.blog.com/posts?page=2"
}
```

In order to query the URL in the `next_page` property, the collection
parser must extract a `{ "page" => "2" }` Hash and forward it to a
`resource_class.where` call:

```ruby
def initialize(parsed = {})
  @elements = parsed["posts"]
  @next_page_uri = URI.parse(parsed["next_page"])
end

def next_page_params
  query_string = @next_page_uri.query

  URI.decode_www_form(query_string).to_h
end

def next_page
  resource_class.where(next_page_params)
end

collection.next_page_params # => { "page" => "2" }
collection.next_page        # => GET https://api.blog.com/posts?page=2
```

The process becomes complicated when there are other parameters
(including "array"-like keys):

```json
{
  "posts": { … },
  "next_page": "https://api.blog.com/posts?tags[]=Ruby&tags[]=Rails&page=2"
}
```

In this scenario, the Array created by [URI.decode_www_form][] will only
retain both `tags[]`-keyed values, but the [Array#to_h][] call will
flatten that Array into a Hash that only contains the last key. In this
case, `tags[]=Ruby` will be omitted, and the resulting Hash would be `{
"tags[]" => "Rails", "page" => "2" }`.

The proposal
---

Active Record's `.where` method supports both [String][] and [Array][]
arguments. In the context of Active Record, `String` and `Array`
arguments are in support of the underlying SQL queries to be executed.

In the context of Active Resource, the underlying format for a "query"
is an HTTP-compliant query that's encoded as an
[application/x-www-form-urlencoded][] string.

This commit proposes adding support to `Base.where` to accept both
String and Array arguments.

This support would simplify the scenario above:

```ruby
def initialize(parsed = {})
  @elements = parsed["posts"]
  @next_page_uri = URI.parse(parsed["next_page"])
end

def next_page
  resource_class.where(@next_page_uri.query)
end

collection.next_page        # => GET https://api.blog.com/posts?page=2
```

When Active Resource is loaded alongside a Rails application, rely on
[ActionDispatch::ParamBuilder.from_pairs][] to decode key-value pairs.
Otherwise, rely on [Array#to_h][].

[URI.decode_www_form]: https://docs.ruby-lang.org/en/master/URI.html#method-c-decode_www_form
[String]: https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where-label-String
[Array]: https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html#method-i-where-label-Array
[application/x-www-form-urlencoded]: https://url.spec.whatwg.org/#application/x-www-form-urlencoded
[ActionDispatch::ParamBuilder.from_pairs]: https://api.rubyonrails.org/classes/ActionDispatch/ParamBuilder.html#method-i-from_pairs
[Array#to_h]: https://docs.ruby-lang.org/en/master/Array.html#method-i-to_h

Author: seanpdoyle

Gemfile

@@ -5,6 +5,7 @@ source "https://rubygems.org"
 git_source(:github) { |repo| "https://github.com/#{repo}" }
 
 branch = ENV.fetch("BRANCH", "main")
+gem "actionpack", github: "rails/rails", branch: branch
 gem "activesupport", github: "rails/rails", branch: branch
 gem "activemodel", github: "rails/rails", branch: branch
 gem "activejob", github: "rails/rails", branch: branch
@@ -18,6 +19,7 @@ gem "rubocop-performance"
 gem "rubocop-rails"
 gem "rubocop-rails-omakase"
 
+gem "minitest", "< 6"
 gem "minitest-bisect"
 
 gemspec

lib/active_resource/base.rb

@@ -1151,7 +1151,52 @@ def all(*args)
 
       # This is an alias for all. You can pass in all the same
       # arguments to this method as you can to <tt>all</tt> and <tt>find(:all)</tt>
+      #
+      # #where accepts conditions in one of several formats. In the examples below, the resulting
+      # URL is given as an illustration.
+      #
+      # === \String
+      #
+      # A string is passed as URL query parameters.
+      #
+      #    Person.where("name=Matz")
+      #    # https://api.people.com/people.json?name=Matz
+      #
+      # === \Array
+      #
+      # If an array is passed, the elements of the array are treated as
+      # name-value pairs. Active Resource takes care of building the query string.
+      # Elements are inserted into the string in the order in which they appear.
+      #
+      #   Person.where([ ["name", "Matz"] ])
+      #   # https://api.people.com/people.json?name=Matz
+      #
+      # When Rails', Action Dispatch's parameter builder support is available
+      # for more complex pairs:
+      #
+      #   Article.where([ ["tags[]", "Ruby"], ["tags[]", "Rails"] ])
+      #   # https://api.people.com/people.json?tags[]=Ruby&tags[]=Rails
+      #
+      #   Person.where([ ["person[name]", "Matz"] ])
+      #   # https://api.people.com/people.json?person[name]=Matz
+      #
+      # === \Hash
+      #
+      # #where will also accept a hash condition, in which the keys are fields and the values
+      # are values to be searched for.
+      #
+      # Fields can be symbols or strings. Values can be single values, arrays, or ranges.
+      #
+      #   Person.where(name: "Matz")
+      #   # https://api.people.com/people.json?name=Matz
+      #
+      #   Person.where(person: { name: "Matz" })
+      #   # https://api.people.com/people.json?person[name]=Matz
+      #
+      #   Article.where(tags: ["Ruby", "Rails"])
+      #   # https://api.people.com/people.json?tags[]=Ruby&tags[]=Rails
       def where(clauses = {})
+        clauses = query_format.decode(clauses) if clauses.is_a?(String) || clauses.is_a?(Array)
         clauses = sanitize_forbidden_attributes(clauses)
         raise ArgumentError, "expected a clauses Hash, got #{clauses.inspect}" unless clauses.is_a? Hash
         all(params: clauses)

lib/active_resource/formats.rb

@@ -14,6 +14,7 @@ def self.[](mime_type_reference)
       case mime_type_reference.to_s
       when "xml" then XmlFormat
       when "json" then JsonFormat
+      when "url_encoded_form" then UrlEncodedFormat
       else ActiveResource::Formats.const_get(ActiveSupport::Inflector.camelize(mime_type_reference.to_s) + "Format")
       end
     end

lib/active_resource/formats/url_encoded_format.rb

@@ -7,10 +7,30 @@ module Formats
     module UrlEncodedFormat
       extend self
 
+      # An object that responds to +#from_pairs+ that transforms an Array of
+      # name value pairs into a params Hash.
+      #
+      #  Defaults to calling Array#to_h when ActionDispatch::ParamBuilder is unavailable.
+      mattr_accessor :param_builder, default: self
+
+      def mime_type
+        "application/x-www-form-urlencoded"
+      end
+
       # URL encode the parameters Hash
       def encode(params, options = nil)
         params.to_query
       end
+
+      # URL decode the query string
+      def decode(query, remove_root = true)
+        query = URI.decode_www_form(query) if query.is_a?(String)
+        param_builder.from_pairs(query)
+      end
+
+      def from_pairs(array) # :nodoc:
+        array.to_h
+      end
     end
   end
 end

lib/active_resource/railtie.rb

@@ -34,6 +34,14 @@ class Railtie < Rails::Railtie
       ActiveSupport.on_load(:active_resource) { self.logger ||= ::Rails.logger }
     end
 
+    initializer "active_resource.url_encoded_form_format" do
+      ActiveSupport.on_load(:action_controller) do
+        require "action_dispatch/http/param_builder"
+
+        ActiveResource::Formats[:url_encoded_form].param_builder = ActionDispatch::ParamBuilder
+      end
+    end
+
     initializer "active_resource.http_mock" do
       ActiveSupport.on_load(:active_support_test_case) do
         teardown { ActiveResource::HttpMock.reset! }

test/cases/finder_test.rb

@@ -8,6 +8,7 @@
 require "fixtures/proxy"
 require "fixtures/pet"
 require "active_support/core_ext/hash/conversions"
+require "action_dispatch/http/param_builder"
 
 module CamelcaseUrlEncodedFormat
   extend ActiveResource::Formats::UrlEncodedFormat
@@ -178,6 +179,54 @@ def test_where_clause_with_permitted_params
     assert_kind_of StreetAddress, addresses.first
   end
 
+  def test_where_clause_string
+    query = URI.encode_www_form([ [ "id", "1" ] ])
+    ActiveResource::HttpMock.respond_to { |m| m.get "/people.json?" + query, {}, @people_david }
+    people = Person.where(query)
+    assert_equal 1, people.size
+    assert_kind_of Person, people.first
+    assert_equal "David", people.first.name
+  end
+
+  def test_where_clause_string_with_multiple_params
+    previous_param_builder = ActiveResource::Formats::UrlEncodedFormat.param_builder
+    ActiveResource::Formats::UrlEncodedFormat.param_builder = ActionDispatch::ParamBuilder
+
+    query = URI.encode_www_form([ [ "id[]", "1" ], [ "id[]", "2" ] ])
+    ActiveResource::HttpMock.respond_to { |m| m.get "/people.json?" + query, {}, @people }
+    people = Person.where(query)
+    assert_equal 2, people.size
+    assert_kind_of Person, people.first
+    assert_kind_of Person, people.second
+    assert_equal [ "Matz", "David" ], people.map(&:name)
+  ensure
+    ActiveResource::Formats::UrlEncodedFormat.param_builder = previous_param_builder
+  end
+
+  def test_where_clause_array
+    ids = [ [ "id", "1" ] ]
+    ActiveResource::HttpMock.respond_to { |m| m.get "/people.json?" + URI.encode_www_form(ids), {}, @people_david }
+    people = Person.where(ids)
+    assert_equal 1, people.size
+    assert_kind_of Person, people.first
+    assert_equal "David", people.first.name
+  end
+
+  def test_where_clause_with_multiple_params
+    previous_param_builder = ActiveResource::Formats::UrlEncodedFormat.param_builder
+    ActiveResource::Formats::UrlEncodedFormat.param_builder = ActionDispatch::ParamBuilder
+
+    ids = [ [ "id[]", "1" ], [ "id[]", "2" ] ]
+    ActiveResource::HttpMock.respond_to { |m| m.get "/people.json?" + URI.encode_www_form(ids), {}, @people }
+    people = Person.where(ids)
+    assert_equal 2, people.size
+    assert_kind_of Person, people.first
+    assert_kind_of Person, people.second
+    assert_equal [ "Matz", "David" ], people.map(&:name)
+  ensure
+    ActiveResource::Formats::UrlEncodedFormat.param_builder = previous_param_builder
+  end
+
   def test_where_with_clause_in
     ActiveResource::HttpMock.respond_to { |m| m.get "/people.json?id%5B%5D=2", {}, @people_david }
     people = Person.where(id: [ 2 ])

test/cases/formats/url_encoded_format_test.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "abstract_unit"
+require "action_dispatch/http/param_builder"
 
 class UrlEncodedFormatTest < ActiveSupport::TestCase
   test "#encode transforms a Hash into an application/x-www-form-urlencoded query string" do
@@ -10,4 +11,88 @@ class UrlEncodedFormatTest < ActiveSupport::TestCase
 
     assert_equal "a=1&b=2&c%5B%5D=3&c%5B%5D=4", encoded
   end
+
+  test "#encode transforms a nested Hash into an application/x-www-form-urlencoded query string" do
+    params = { "person" => { "name" => "Matz" } }
+
+    encoded = ActiveResource::Formats::UrlEncodedFormat.encode(params)
+
+    assert_equal "person%5Bname%5D=Matz", encoded
+  end
+
+  test "#decode transforms an application/x-www-form-urlencoded query string into a Hash" do
+    query = URI.encode_www_form([ [ "a", "1" ] ])
+
+    decoded = ActiveResource::Formats::UrlEncodedFormat.decode(query)
+
+    assert_equal({ "a" => "1" }, decoded)
+  end
+
+  test "#decode transforms an Array of query string pairs into a Hash" do
+    pairs = [ [ "a", "1" ] ]
+
+    decoded = ActiveResource::Formats::UrlEncodedFormat.decode(pairs)
+
+    assert_equal({ "a" => "1" }, decoded)
+  end
+
+  test "#decode transforms an Array of nested query string pairs into a Hash" do
+    pairs = [ [ "person[name]", "Matz" ] ]
+
+    decoded = ActiveResource::Formats::UrlEncodedFormat.decode(pairs)
+
+    assert_equal({ "person[name]" => "Matz" }, decoded)
+  end
+
+  test "#decode transforms an application/x-www-form-urlencoded query string with multiple params into a Hash" do
+    format = ActiveResource::Formats::UrlEncodedFormat
+    previous_param_builder = format.param_builder
+    format.param_builder = ActionDispatch::ParamBuilder
+
+    query = URI.encode_www_form([ [ "a[]", "1" ], [ "a[]", "2" ] ])
+
+    decoded = format.decode(query)
+
+    assert_equal({ "a" => [ "1", "2" ] }, decoded)
+  ensure
+    format.param_builder = previous_param_builder
+  end
+
+  test "#decode transforms an Array of query string pairs with multiple params into a Hash" do
+    format = ActiveResource::Formats::UrlEncodedFormat
+    previous_param_builder = format.param_builder
+    format.param_builder = ActionDispatch::ParamBuilder
+
+    pairs = [ [ "a[]", "1" ], [ "a[]", "2" ] ]
+
+    decoded = format.decode(pairs)
+
+    assert_equal({ "a" => [ "1", "2" ] }, decoded)
+  ensure
+    format.param_builder = previous_param_builder
+  end
+
+  test "#decode transforms an Array of nested query string pairs into a Hash using ActionDispatch::ParamBuilder" do
+    format = ActiveResource::Formats::UrlEncodedFormat
+    previous_param_builder = format.param_builder
+    format.param_builder = ActionDispatch::ParamBuilder
+
+    pairs = [ [ "person[name]", "Matz" ] ]
+
+    decoded = format.decode(pairs)
+
+    assert_equal({ "person" => { "name" => "Matz" } }, decoded)
+  ensure
+    format.param_builder = previous_param_builder
+  end
+
+  test "#decode returns a Hash of query string pairs" do
+    decoded = ActiveResource::Formats::UrlEncodedFormat.decode("a" => "1")
+
+    assert_equal({ "a" => "1" }, decoded)
+  end
+
+  test "#mime_type returns application/x-www-form-urlencoded" do
+    assert_equal "application/x-www-form-urlencoded", ActiveResource::Formats::UrlEncodedFormat.mime_type
+  end
 end

test/cases/formats_test.rb

@@ -11,6 +11,11 @@ def test_xml_format_uses_camelcase
     assert_equal ActiveResource::Formats::XmlFormat, ActiveResource::Formats[:xml]
   end
 
+  def test_url_encoded_format
+    assert_equal ActiveResource::Formats::UrlEncodedFormat, ActiveResource::Formats[:url_encoded]
+    assert_equal ActiveResource::Formats::UrlEncodedFormat, ActiveResource::Formats[:url_encoded_form]
+  end
+
   def test_custom_format_uses_camelcase
     klass = Class.new
     ActiveResource::Formats.const_set(:MsgpackFormat, klass)