Introduce Base.query_format for URL encoding values

Follow-up to [#421][]

Problem
---

Not all HTTP APIs support `snake_case` query parameters. Active
Resource's built-in finders (like `.find(:all, params: { … })`,
`.all(params: { … })`, `where(…)`) do not support transforming keys
prior to their encoding.

If an API expects camelCase keys (like `?firstName=Matz` rather than
`?first_name=Matz`), Active Resource's does not provide a method or hook
to override. The already defined `Base.query_string` method used by the
current implementation is `private`. If a consumer were to override it
(despite depending on or overriding `private` methods being
discouraged), they would need to be responsible for transforming the
`Hash` *and* encoding it to a `String`.

Proposal
---

This commit proposed the introduction of the
`ActiveResource::Formats::UrlEncodedFormat`. It's modeled after the
`XmlFormat` and `JsonFormat`, and defines an `encode` method with the
prior behavior (a call to [Hash#to_query][]). Along with the new class,
this commit also introduce a new `.query_format` class attribute (with
getter and setter methods), modeled after the `.format` class attribute.

Consumers can provide their own implementation with or without depending
on the `ActiveResource::Formats::UrlEncodedFormat`. For example, callers
can camelCase keys:

```ruby
module CamelcaseUrlEncodedFormat
  extend self, ActiveResource::Formats::UrlEncodedFormat

  def encode(params, options = nil)
    params = params.deep_transform { |key| key.to_s.camelcase(:lower) }

    super
  end
end

class Person < ActiveResource::Base
  self.site = "https://example.com"
  self.query_format = CamelcaseUrlEncodedFormat
end

Person.where(first_name: "Sean")
 # => GET https://example.com/people.json?firstName=Sean
```

The URL encoding only applies to query parameters. Prefix options remain
snake_case:

```ruby
class Person < ActiveResource::Base
  self.site = "https://example.com"
  self.prefix = "/teams/:team_id"
  self.query_format = CamelcaseUrlEncodedFormat
end

Person.where(team_id: 1, first_name: "Sean")
 # => GET https://example.com/teams/1/people.json?firstName=Sean
```

This commit also includes changes to the `README.md` example code's
query parameters to demonstrate that keys are `snake_case` by default.

[#421]: #421
[Hash#to_query]: https://api.rubyonrails.org/classes/Hash.html#method-i-to_query

Author: seanpdoyle

README.md

@@ -132,7 +132,7 @@ response:
 ```ruby
 # Expects a response of
 #
-# {"id":1,"first":"Tyler","last":"Durden"}
+# {"id":1,"first_name":"Tyler","last_name":"Durden"}
 #
 # for GET http://api.people.com:3000/people/1.json
 #
@@ -144,14 +144,14 @@ JSON element becoming an attribute on the object.
 
 ```ruby
 tyler.is_a? Person  # => true
-tyler.last  # => 'Durden'
+tyler.last_name  # => 'Durden'
 ```
 
 Any complex element (one that contains other elements) becomes its own object:
 
 ```ruby
 # With this response:
-# {"id":1,"first":"Tyler","address":{"street":"Paper St.","state":"CA"}}
+# {"id":1,"first_name":"Tyler","address":{"street":"Paper St.","state":"CA"}}
 #
 # for GET http://api.people.com:3000/people/1.json
 #
@@ -166,15 +166,30 @@ Collections can also be requested in a similar fashion
 # Expects a response of
 #
 # [
-#   {"id":1,"first":"Tyler","last":"Durden"},
-#   {"id":2,"first":"Tony","last":"Stark",}
+#   {"id":1,"first_name":"Tyler","last_name":"Durden"},
+#   {"id":2,"first_name":"Tony","last_name":"Stark",}
 # ]
 #
 # for GET http://api.people.com:3000/people.json
 #
 people = Person.all
-people.first  # => <Person::xxx 'first' => 'Tyler' ...>
-people.last  # => <Person::xxx 'first' => 'Tony' ...>
+people.first  # => <Person::xxx 'first_name' => 'Tyler' ...>
+people.last  # => <Person::xxx 'first_name' => 'Tony' ...>
+```
+
+Collections can be filtered with query parameters
+
+```ruby
+# Expects a response of
+#
+# [
+#   {"id":1,"first_name":"Tyler","last_name":"Durden"},
+# ]
+#
+# for GET http://api.people.com:3000/people.json?last_name=Durden
+#
+people = Person.where(last_name: "Durden")
+people.first  # => <Person::xxx 'first_name' => 'Tyler' ...>
 ```
 
 ### Create
@@ -185,12 +200,12 @@ id of the newly created resource is parsed out of the Location response header a
 as the id of the ARes object.
 
 ```ruby
-# {"first":"Tyler","last":"Durden"}
+# {"first_name":"Tyler","last_name":"Durden"}
 #
 # is submitted as the body on
 #
-# if include_root_in_json is not set or set to false => {"first":"Tyler"}
-# if include_root_in_json is set to true => {"person":{"first":"Tyler"}}
+# if include_root_in_json is not set or set to false => {"first_name":"Tyler"}
+# if include_root_in_json is set to true => {"person":{"first_name":"Tyler"}}
 #
 # POST http://api.people.com:3000/people.json
 #
@@ -199,7 +214,7 @@ as the id of the ARes object.
 #
 # Response (201): Location: http://api.people.com:3000/people/2
 #
-tyler = Person.new(:first => 'Tyler')
+tyler = Person.new(:first_name => 'Tyler')
 tyler.new?  # => true
 tyler.save  # => true
 tyler.new?  # => false
@@ -213,21 +228,21 @@ with the exception that no response headers are needed -- just an empty response
 server side was successful.
 
 ```ruby
-# {"first":"Tyler"}
+# {"first_name":"Tyler"}
 #
 # is submitted as the body on
 #
-# if include_root_in_json is not set or set to false => {"first":"Tyler"}
-# if include_root_in_json is set to true => {"person":{"first":"Tyler"}}
+# if include_root_in_json is not set or set to false => {"first_name":"Tyler"}
+# if include_root_in_json is set to true => {"person":{"first_name":"Tyler"}}
 #
 # PUT http://api.people.com:3000/people/1.json
 #
 # when save is called on an existing Person object.  An empty response is
 # is expected with code (204)
 #
 tyler = Person.find(1)
-tyler.first # => 'Tyler'
-tyler.first = 'Tyson'
+tyler.first_name # => 'Tyler'
+tyler.first_name = 'Tyson'
 tyler.save  # => true
 ```
 

lib/active_resource/base.rb

@@ -380,6 +380,7 @@ def self.logger=(logger)
       @@logger = logger
     end
 
+    class_attribute :_query_format
     class_attribute :_format
     class_attribute :_collection_parser
     class_attribute :include_format_in_path
@@ -623,6 +624,24 @@ def auth_type=(auth_type)
         @auth_type = auth_type
       end
 
+      # Sets the URL format that attributes are sent and received in from a mime type reference:
+      #
+      #   Person.query_format = ActiveResource::Formats::UrlEncodedFormat
+      #   Person.where(first_name: "Matz") # => GET /people.json?first_name=Matz
+      #
+      #   Person.query_format = CustomCamelcaseUrlEncodedFormat
+      #   Person.where(first_name: "Matz") # => GET /people.json?firstName=Matz
+      #
+      # Default format is <tt>ActiveResource::Formats::UrlEncodedFormat</tt>.
+      def query_format=(mime_type_reference_or_format)
+        self._query_format = mime_type_reference_or_format
+      end
+
+      # Returns the current parameters format, default is ActiveResource::Formats::UrlEncodedFormat
+      def query_format
+        self._query_format || ActiveResource::Formats::UrlEncodedFormat
+      end
+
       # Sets the format that attributes are sent and received in from a mime type reference:
       #
       #   Person.format = :json
@@ -1032,7 +1051,8 @@ def create!(attributes = {})
       # ==== Options
       #
       # * <tt>:from</tt> - Sets the path or custom method that resources will be fetched from.
-      # * <tt>:params</tt> - Sets query and \prefix (nested URL) parameters.
+      # * <tt>:params</tt> - Sets query and \prefix (nested URL) parameters. Query keys are URL
+      #                      encoded using the resource's +query_format+ (the ActiveResource::Formats::UrlEncodedFormat by default).
       #
       # ==== Examples
       #   Person.find(1)
@@ -1118,6 +1138,8 @@ def all(*args)
         WhereClause.new(self, *args)
       end
 
+      # 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>
       def where(clauses = {})
         clauses = sanitize_forbidden_attributes(clauses)
         raise ArgumentError, "expected a clauses Hash, got #{clauses.inspect}" unless clauses.is_a? Hash
@@ -1243,7 +1265,7 @@ def prefix_parameters
 
         # Builds the query string for the request.
         def query_string(options)
-          "?#{options.to_query}" unless options.nil? || options.empty?
+          "?#{query_format.encode(options)}" unless options.nil? || options.empty?
         end
 
         # split an option hash into two hashes, one containing the prefix options,

lib/active_resource/formats.rb

@@ -4,6 +4,7 @@ module ActiveResource
   module Formats
     autoload :XmlFormat, "active_resource/formats/xml_format"
     autoload :JsonFormat, "active_resource/formats/json_format"
+    autoload :UrlEncodedFormat, "active_resource/formats/url_encoded_format"
 
     # Lookup the format class from a mime type reference symbol. Example:
     #

lib/active_resource/formats/url_encoded_format.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/array/wrap"
+
+module ActiveResource
+  module Formats
+    module UrlEncodedFormat
+      extend self
+
+      # URL encode the parameters Hash
+      def encode(params, options = nil)
+        params.to_query
+      end
+    end
+  end
+end

test/abstract_unit.rb

@@ -32,6 +32,7 @@ def setup_response
   @joe    = { person: { id: 6, name: "Joe", likes_hats: true } }.to_json
   @people = { people: [ { person: { id: 1, name: "Matz" } }, { person: { id: 2, name: "David" } } ] }.to_json
   @people_david = { people: [ { person: { id: 2, name: "David" } } ] }.to_json
+  @people_joe = { people: [ { id: 6, name: "Joe", likes_hats: true } ] }.to_json
   @addresses = { addresses: [ { address: { id: 1, street: "12345 Street", country: "Australia" } } ] }.to_json
   @post  = { id: 1, title: "Hello World", body: "Lorem Ipsum" }.to_json
   @posts = [ { id: 1, title: "Hello World", body: "Lorem Ipsum" }, { id: 2, title: "Second Post", body: "Lorem Ipsum" } ].to_json

test/cases/finder_test.rb

@@ -9,6 +9,24 @@
 require "fixtures/pet"
 require "active_support/core_ext/hash/conversions"
 
+module CamelcaseUrlEncodedFormat
+  extend ActiveResource::Formats::UrlEncodedFormat
+
+  def self.encode(params, options = nil)
+    params = params.deep_transform_keys { |key| key.to_s.camelcase(:lower) }
+
+    super
+  end
+end
+
+class CamelcasePerson < Person
+  self.query_format = CamelcaseUrlEncodedFormat
+end
+
+class CamelcasePet < Pet
+  self.query_format = CamelcaseUrlEncodedFormat
+end
+
 class FinderTest < ActiveSupport::TestCase
   def setup
     setup_response # find me in abstract_unit
@@ -143,6 +161,15 @@ def test_where_with_clause_in
     assert_equal "David", people.first.name
   end
 
+  def test_where_with_clause_in_custom_query_format
+    ActiveResource::HttpMock.respond_to { |m| m.get "/camelcase_people.json?likesHats=true", {}, @people_joe }
+    people = CamelcasePerson.where(likes_hats: true)
+    assert_equal 1, people.size
+    assert_kind_of CamelcasePerson, people.first
+    assert_equal "Joe", people.first.name
+    assert_predicate people.first, :likes_hats
+  end
+
   def test_where_with_invalid_clauses
     error = assert_raise(ArgumentError) { Person.where(nil) }
     assert_equal "expected a clauses Hash, got nil", error.message
@@ -230,6 +257,18 @@ def test_find_all_by_from_with_prefix
     assert_equal ({ person_id: 1 }), pets.second.prefix_options
   end
 
+  def test_find_all_with_prefix_and_custom_query_format
+    ActiveResource::HttpMock.respond_to { |m| m.get "/people/1/camelcase_pets.json?queryParam=1", {}, @pets }
+
+    pets = CamelcasePet.find(:all, params: { person_id: 1, query_param: 1 })
+    assert_equal 2, pets.size
+    assert_equal "Max", pets.first.name
+    assert_equal ({ person_id: 1 }), pets.first.prefix_options
+
+    assert_equal "Daisy", pets.second.name
+    assert_equal ({ person_id: 1 }), pets.second.prefix_options
+  end
+
   def test_find_all_by_symbol_from
     ActiveResource::HttpMock.respond_to { |m| m.get "/people/managers.json", {}, @people_david }
 

test/cases/formats/url_encoded_format_test.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "abstract_unit"
+
+class UrlEncodedFormatTest < ActiveSupport::TestCase
+  test "#encode transforms a Hash into an application/x-www-form-urlencoded query string" do
+    params = { "a" => 1, "b" => 2, "c" => [ 3, 4 ] }
+
+    encoded = ActiveResource::Formats::UrlEncodedFormat.encode(params)
+
+    assert_equal "a=1&b=2&c%5B%5D=3&c%5B%5D=4", encoded
+  end
+end