Singletons: Default collection_name to singleton_name

The problem
---

Active Resource's custom methods are operations outside of the
conventional collection of CRUD actions. For typical collections of
resources, custom methods operate on the collection itself. For example,
consider a custom `refresh` action for a `Product` resource triggered by
`POST` requests: `POST /products/:product_id/refresh`. The route
utilizes a `:product_id` dynamic segment to identify the `Product` in
question, and the path includes `/refresh` to signify the custom method
to perform.

The concept of a "singleton" resource is that there is only one singular
resource, and operations should consistently modify the same resource.
Since the resource is singular in nature, paths *do not* identify that
resource with an ID. For example, consider a singleton `Inventory`
resource that belongs to a `Product`. Its singleton path would be
`/products/:product_id/inventory`.

Prior to this commit, custom methods invoked by both *instances* and
*classes* of singleton resources ignored the "singleton" nature of
route, and use pluralize nouns instead of singular ones.

For example, consider calls to custom "report" and "reset" methods for
an instance of a singleton `Inventory` resource:

```ruby
inventory = Inventory.find(params: { product_id: 1 }) # => GET /products/1/inventory.json

  # BEFORE
inventory.get(:report, product_id: 1)   # => GET /products/1/inventories/report.json
inventory.delete(:reset, product_id: 1) # => DELETE /products/1/inventories/reset.json
```

Note the `/inventories/` portion of the URL prefix. The same occurs for
class methods. For example, consider calls to the same custom "report"
and "reset" routes for a singleton `Inventory` resource class:

```ruby
 # BEFORE
Inventory.get(:report, product_id: 1)   # => GET /products/1/inventories/report.json
Inventory.delete(:reset, product_id: 1) # => DELETE /products/1/inventories/reset.json
```

The proposal
---

In order to make "singleton" resources behave more consistently with a
singular mental model, this commit proposes that Active Resource change
instance-level custom methods (through the same `get`, `post`, `put`,
`patch`, and `delete` style methods) to use the singular singleton name
in their paths.

When declaring a resource as a "singleton" (through including the
`ActiveResource::Singleton` module), ensure that subsequent calls to
class-level custom methods (through the `get`, `post`, `put`, `patch`,
and `delete` class and instance methods) use the singleton name by
default.

```ruby
  # AFTER
Inventory.get(:report, product_id: 1)   # => GET /products/1/inventory/report.json
Inventory.delete(:reset, product_id: 1) # => DELETE /products/1/inventory/reset.json
```

When a `collection_name` is explicitly configured, use that value
instead of the `singleton_name` default.

Apply the same changes to instances of singleton resources:

```ruby
inventory = Inventory.find(params: { product_id: 1 }) # => GET /products/1/inventory.json

  # AFTER
inventory.get(:report)    # => GET /products/1/inventory/report.json
inventory.delete(:reset)  # => DELETE /products/1/inventory/reset.json
```

Author: seanpdoyle

lib/active_resource/singleton.rb

@@ -1,6 +1,25 @@
 # frozen_string_literal: true
 
 module ActiveResource
+  # === Custom REST methods
+  #
+  # Since simple CRUD/life cycle methods can't accomplish every task, Singleton Resources can also support
+  # defining custom REST methods. To invoke them, Active Resource provides the <tt>get</tt>,
+  # <tt>post</tt>, <tt>put</tt> and <tt>delete</tt> methods where you can specify a custom REST method
+  # name to invoke.
+  #
+  # Singleton resources use their <tt>singleton_name</tt> value as their default
+  # <tt>collection_name</tt> value when constructing the request's path.
+  #
+  #   # GET to report on the Inventory, i.e. GET /products/1/inventory/report.json.
+  #   Inventory.get(:report, product_id: 1)
+  #   # => [{:count => 'Manager'}, {:name => 'Clerk'}]
+  #
+  #   # DELETE to 'reset' an inventory, i.e. DELETE /products/1/inventory/reset.json.
+  #   Inventory.find(params: { product_id: 1 }).delete(:reset)
+  #
+  # For more information on using custom REST methods, see the
+  # ActiveResource::CustomMethods documentation.
   module Singleton
     extend ActiveSupport::Concern
 
@@ -11,6 +30,10 @@ def singleton_name
         @singleton_name ||= model_name.element
       end
 
+      def collection_name
+        @collection_name || singleton_name
+      end
+
       # Gets the singleton path for the object.  If the +query_options+ parameter is omitted, Rails
       # will split from the \prefix options.
       #
@@ -107,5 +130,9 @@ def create
       def singleton_path(options = nil)
         self.class.singleton_path(options || prefix_options)
       end
+
+      def custom_method_element_url(method_name, options = {})
+        "#{self.class.prefix(prefix_options)}#{self.class.collection_name}/#{method_name}#{self.class.format_extension}#{self.class.__send__(:query_string, options)}"
+      end
   end
 end

test/cases/base/custom_methods_test.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "abstract_unit"
+require "fixtures/inventory"
 require "fixtures/person"
 require "fixtures/street_address"
 require "active_support/core_ext/hash/conversions"
@@ -13,6 +14,8 @@ def setup
     @ryan  = { person: { name: "Ryan" } }.to_json
     @addy  = { address: { id: 1, street: "12345 Street" } }.to_json
     @addy_deep = { address: { id: 1, street: "12345 Street", zip: "27519" } }.to_json
+    @inventory = { inventory: { id: 1, name: "Warehouse" } }.to_json
+    @inventory_array = { inventory: [{ id: 1, name: "Warehouse" }] }.to_json
 
     ActiveResource::HttpMock.respond_to do |mock|
       mock.get    "/people/1.json",        {}, @matz
@@ -33,6 +36,13 @@ def setup
       mock.put    "/people/1/addresses/1/normalize_phone.json?locale=US", {}, nil, 204
       mock.put    "/people/1/addresses/sort.json?by=name", {}, nil, 204
       mock.post   "/people/1/addresses/new/link.json", {}, { address: { street: "12345 Street" } }.to_json, 201, "Location" => "/people/1/addresses/2.json"
+      mock.get    "/products/1/inventory.json", {}, @inventory
+      mock.get    "/products/1/inventory/shallow.json", {}, @inventory
+      mock.get    "/products/1/inventory/retrieve.json?name=Warehouse", {}, @inventory_array
+      mock.post   "/products/1/inventory/purchase.json?name=Warehouse", {}, nil, 201
+      mock.put    "/products/1/inventory/promote.json?name=Warehouse", {}, nil, 204
+      mock.put    "/products/1/inventory/sort.json?by=name", {}, nil, 204
+      mock.delete "/products/1/inventory/deactivate.json", {}, nil, 200
     end
 
     Person.user = nil
@@ -97,6 +107,43 @@ def test_custom_new_element_method
     assert_equal ActiveResource::Response.new(@matz, 201), matz.post(:register)
   end
 
+  def test_singleton_custom_collection_method
+    # GET
+    assert_equal([{ "id" => 1, "name" => "Warehouse" }], Inventory.get(:retrieve, product_id: 1, name: "Warehouse"))
+
+    # POST
+    assert_equal(ActiveResource::Response.new("", 201, {}), Inventory.post(:purchase, product_id: 1, name: "Warehouse"))
+
+    # PUT
+    assert_equal ActiveResource::Response.new("", 204, {}),
+                   Inventory.put(:promote, { product_id: 1, name: "Warehouse" }, "atestbody")
+    assert_equal ActiveResource::Response.new("", 204, {}), Inventory.put(:sort, product_id: 1, by: "name")
+  end
+
+  def test_singleton_custom_collection_method_with_overridden_collection_name
+    original_collection_name, Inventory.collection_name = Inventory.collection_name, "special_inventory"
+
+    ActiveResource::HttpMock.respond_to.get "/products/1/special_inventory/shallow.json", {}, @inventory
+
+    # GET
+    assert_equal({ "id" => 1, "name" => "Warehouse" }, Inventory.get(:shallow, product_id: 1))
+  ensure
+    Inventory.collection_name = original_collection_name
+  end
+
+  def test_singleton_custom_element_method
+    inventory = Inventory.find(params: { product_id: 1 })
+
+    # Test GET against an element URL
+    assert_equal inventory.get(:shallow), "id" => 1, "name" => "Warehouse"
+
+    # Test PUT against an element URL
+    assert_equal ActiveResource::Response.new("", 204, {}), inventory.put(:promote, { name: "Warehouse" }, "body")
+
+    # Test DELETE against an element URL
+    assert_equal ActiveResource::Response.new("", 200, {}), inventory.delete(:deactivate)
+  end
+
   def test_find_custom_resources
     assert_equal "Matz", Person.find(:all, from: :managers).first.name
   end