Allow for include parameter on listing and showing roles

* GET /v3/roles?include=user & GET /v3/roles/:guid?include=user
endpoints
* Moved a controller function that makes the call to UAA to get
usernames and origins into the user model so it could be shared by the
decorators
* Updated docs

[#164176870]

Co-authored-by: Merric de Launey <[email protected]>
Co-authored-by: Mona Mohebbi <[email protected]>

app/controllers/v3/roles_controller.rb

@@ -1,10 +1,12 @@
 require 'messages/role_create_message'
 require 'messages/roles_list_message'
+require 'messages/role_show_message'
 require 'fetchers/role_list_fetcher'
 require 'actions/role_create'
 require 'actions/role_guid_populate'
 require 'actions/role_delete'
 require 'presenters/v3/role_presenter'
+require 'decorators/include_role_user_decorator'
 
 class RolesController < ApplicationController
   def create
@@ -29,19 +31,29 @@ def index
     RoleGuidPopulate.populate
     roles = RoleListFetcher.fetch(message, readable_roles)
 
+    decorators = []
+    decorators << IncludeRoleUserDecorator if IncludeRoleUserDecorator.match?(message.include)
+
     render status: :ok, json: Presenters::V3::PaginatedListPresenter.new(
       presenter: Presenters::V3::RolePresenter,
       paginated_result: SequelPaginator.new.get_page(roles, message.try(:pagination_options)),
       path: '/v3/roles',
-      message: message
+      message: message,
+      decorators: decorators,
     )
   end
 
   def show
+    message = RoleShowMessage.from_params(query_params)
+    unprocessable!(message.errors.full_messages) unless message.valid?
+
+    decorators = []
+    decorators << IncludeRoleUserDecorator if IncludeRoleUserDecorator.match?(message.include)
+
     role = readable_roles.first(guid: hashed_params[:guid])
     resource_not_found!(:role) unless role
 
-    render status: :ok, json: Presenters::V3::RolePresenter.new(role)
+    render status: :ok, json: Presenters::V3::RolePresenter.new(role, decorators: decorators)
   end
 
   def destroy

app/controllers/v3/users_controller.rb

@@ -20,7 +20,7 @@ def index
       paginated_result: SequelPaginator.new.get_page(users, message.try(:pagination_options)),
       path: '/v3/users',
       message: message,
-      extra_presenter_args: { uaa_users: uaa_users_info(user_guids) },
+      extra_presenter_args: { uaa_users: User.uaa_users_info(user_guids) },
     )
   end
 
@@ -31,7 +31,7 @@ def create
     unprocessable!(message.errors.full_messages) unless message.valid?
     user = UserCreate.new.create(message: message)
 
-    render status: :created, json: Presenters::V3::UserPresenter.new(user, uaa_users: uaa_users_info([user.guid]))
+    render status: :created, json: Presenters::V3::UserPresenter.new(user, uaa_users: User.uaa_users_info([user.guid]))
   rescue UserCreate::Error => e
     unprocessable!(e)
   end
@@ -40,7 +40,7 @@ def show
     user = fetch_user_if_readable(hashed_params[:guid])
     user_not_found! unless user
 
-    render status: :ok, json: Presenters::V3::UserPresenter.new(user, uaa_users: uaa_users_info([user.guid]))
+    render status: :ok, json: Presenters::V3::UserPresenter.new(user, uaa_users: User.uaa_users_info([user.guid]))
   end
 
   def destroy
@@ -68,7 +68,7 @@ def update
 
     user = UserUpdate.new.update(user: user, message: message)
 
-    render status: :ok, json: Presenters::V3::UserPresenter.new(user, uaa_users: uaa_users_info([hashed_params[:guid]]))
+    render status: :ok, json: Presenters::V3::UserPresenter.new(user, uaa_users: User.uaa_users_info([hashed_params[:guid]]))
   end
 
   private
@@ -83,11 +83,6 @@ def fetch_user_if_readable(desired_guid)
     readable_users.first(guid: desired_guid)
   end
 
-  def uaa_users_info(user_guids)
-    uaa_client = CloudController::DependencyLocator.instance.uaa_client
-    uaa_client.users_for_ids(user_guids)
-  end
-
   def user_not_found!
     resource_not_found!(:user)
   end

app/decorators/include_role_user_decorator.rb

@@ -0,0 +1,21 @@
+# require 'models/runtime/user'
+
+module VCAP::CloudController
+  class IncludeRoleUserDecorator
+    class << self
+      def match?(include_params)
+        include_params&.include?('user')
+      end
+
+      def decorate(hash, roles)
+        hash[:included] ||= {}
+        user_guids = roles.map(&:user_guid).uniq
+        users = User.where(guid: user_guids).order(:created_at)
+        uaa_users = User.uaa_users_info(user_guids)
+
+        hash[:included][:users] = users.map { |user| Presenters::V3::UserPresenter.new(user, uaa_users: uaa_users).to_hash }
+        hash
+      end
+    end
+  end
+end

app/messages/role_show_message.rb

@@ -0,0 +1,14 @@
+require 'messages/base_message'
+
+module VCAP::CloudController
+  class RoleShowMessage < BaseMessage
+    register_allowed_keys [:include]
+
+    validates_with NoAdditionalParamsValidator
+    validates_with IncludeParamValidator, valid_values: ['user']
+
+    def self.from_params(params)
+      super(params, %w(include))
+    end
+  end
+end

app/messages/roles_list_message.rb

@@ -7,10 +7,12 @@ class RolesListMessage < ListMessage
       :organization_guids,
       :space_guids,
       :user_guids,
-      :types
+      :types,
+      :include
     ]
 
     validates_with NoAdditionalParamsValidator
+    validates_with IncludeParamValidator, valid_values: ['user']
 
     validates :guids, allow_nil: true, array: true
     validates :organization_guids, allow_nil: true, array: true
@@ -21,7 +23,7 @@ class RolesListMessage < ListMessage
     def self.from_params(params)
       params['order_by'] ||= 'created_at'
 
-      super(params, %w(guids organization_guids space_guids user_guids types))
+      super(params, %w(guids organization_guids space_guids user_guids types include))
     end
   end
 end

app/models/runtime/user.rb

@@ -201,6 +201,11 @@ def visible_users_in_my_orgs
         distinct
     end
 
+    def self.uaa_users_info(user_guids)
+      uaa_client = CloudController::DependencyLocator.instance.uaa_client
+      uaa_client.users_for_ids(user_guids)
+    end
+
     def self.readable_users_for_current_user(can_read_globally, current_user)
       if can_read_globally
         User.dataset

app/presenters/v3/role_presenter.rb

@@ -3,14 +3,15 @@
 module VCAP::CloudController::Presenters::V3
   class RolePresenter < BasePresenter
     def to_hash
-      {
+      hash = {
         guid: role.guid,
         created_at: role.created_at,
         updated_at: role.updated_at,
         type: role.type,
         relationships: build_relationships,
         links: build_links
       }
+      @decorators.reduce(hash) { |memo, d| d.decorate(memo, [role]) }
     end
 
     private

docs/v3/source/includes/experimental_resources/roles/_get.md.erb

@@ -27,6 +27,12 @@ This endpoint gets an individual role resource.
 
 `GET /v3/roles/:guid`
 
+#### Query parameters
+
+Name | Type | Description
+---- | ---- | ------------
+**include** | _string_ | **Experimental** - Optionally include a list of unique related resources in the response. <br>The only valid value is `user`
+
 #### Permitted roles
 
 Role | Notes

docs/v3/source/includes/experimental_resources/roles/_list.md.erb

@@ -39,6 +39,8 @@ Name | Type | Description
 **page** | _integer_ | Page to display. Valid values are integers >= 1.
 **per_page** | _integer_ | Number of results per page. <br>Valid values are 1 through 5000.
 **order_by** | _string_ | Value to sort by. Defaults to ascending. Prepend with `-` to sort descending. <br>Valid values are `created_at`, `updated_at`.
+**include** | _string_ | **Experimental** - Optionally include a list of unique related resources in the response. <br>The only valid value is `user`
+
 
 #### Permitted roles
  |