v3(services): SI usage summary in shared spaces (cloudfoundry#1765)

[finishes #171937145](https://www.pivotaltracker.com/story/show/171937145)

Author: Derik Evangelista

app/controllers/v3/service_instances_controller.rb

@@ -11,6 +11,7 @@
 require 'presenters/v3/to_many_relationship_presenter'
 require 'presenters/v3/paginated_list_presenter'
 require 'presenters/v3/service_instance_presenter'
+require 'presenters/v3/shared_spaces_usage_summary_presenter'
 require 'actions/service_instance_share'
 require 'actions/service_instance_unshare'
 require 'actions/service_instance_update_managed'
@@ -182,6 +183,13 @@ def relationships_shared_spaces
     )
   end
 
+  def shared_spaces_usage_summary
+    service_instance = ServiceInstance.first(guid: hashed_params[:guid])
+    service_instance_not_found! unless service_instance.present? && can_read_space?(service_instance.space)
+
+    render status: :ok, json: Presenters::V3::SharedSpacesUsageSummaryPresenter.new(service_instance)
+  end
+
   def credentials
     service_instance = UserProvidedServiceInstance.first(guid: hashed_params[:guid])
     service_instance_not_found! unless service_instance && can_read_service_instance?(service_instance)

app/presenters/v3/shared_spaces_usage_summary_presenter.rb

@@ -0,0 +1,51 @@
+require 'presenters/v3/base_presenter'
+
+module VCAP::CloudController
+  module Presenters
+    module V3
+      class SharedSpacesUsageSummaryPresenter < BasePresenter
+        def to_hash
+          {
+            usage_summary: build_usage_summary,
+            links: build_links
+          }
+        end
+
+        private
+
+        def service_instance
+          @resource
+        end
+
+        def build_usage_summary
+          count = Hash.new(0).tap do |h|
+            service_instance.service_bindings.each do |binding|
+              h[binding.app.space.guid] += 1
+            end
+          end
+
+          service_instance.shared_spaces.sort_by(&:id).map do |space|
+            {
+              space: { guid: space.guid },
+              bound_app_count: count[space.guid]
+            }
+          end
+        end
+
+        def build_links
+          {
+            self: {
+              href: url_builder.build_url(path: "/v3/service_instances/#{service_instance.guid}/relationships/shared_spaces/usage_summary")
+            },
+            shared_spaces: {
+              href: url_builder.build_url(path: "/v3/service_instances/#{service_instance.guid}/relationships/shared_spaces")
+            },
+            service_instance: {
+              href: url_builder.build_url(path: "/v3/service_instances/#{service_instance.guid}")
+            }
+          }
+        end
+      end
+    end
+  end
+end

config/routes.rb

@@ -218,6 +218,7 @@
   get '/service_instances', to: 'service_instances_v3#index'
   get '/service_instances/:guid', to: 'service_instances_v3#show'
   get '/service_instances/:service_instance_guid/relationships/shared_spaces', to: 'service_instances_v3#relationships_shared_spaces'
+  get '/service_instances/:guid/relationships/shared_spaces/usage_summary', to: 'service_instances_v3#shared_spaces_usage_summary'
   get '/service_instances/:guid/credentials', to: 'service_instances_v3#credentials'
   get '/service_instances/:guid/parameters', to: 'service_instances_v3#parameters'
   post '/service_instances', to: 'service_instances_v3#create'

docs/v3/source/includes/api_resources/_service_instances.erb

@@ -214,4 +214,32 @@
 }
 <% end %>
 
-
+<% content_for :shared_spaces_usage_summary do %>
+{
+  "usage_summary": [
+    {
+      "space": {
+        "guid": "68d54d31-9b3a-463b-ba94-e8e4c32edbac"
+      },
+      "bound_app_count": 2
+    },
+    {
+      "space": {
+        "guid": "b19f6525-cbd3-4155-b156-dc0c2a431b4c"
+      },
+      "bound_app_count": 0
+    }
+  ],
+  "links": {
+    "self": {
+      "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces/usage_summary"
+    },
+    "shared_spaces": {
+      "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c/relationships/shared_spaces"
+    },
+    "service_instance": {
+      "href": "https://api.example.org/v3/service_instances/bdeg4371-cbd3-4155-b156-dc0c2a431b4c"
+    }
+  }
+}
+<% end %>

docs/v3/source/includes/experimental_resources/service_instances/_get_shared_spaces_usage_summary.md.erb

@@ -0,0 +1,38 @@
+### Get usage summary in shared spaces
+
+```
+Example Request
+```
+
+```shell
+curl "https://api.example.org/v3/service_instances/[guid]/relationships/shared_spaces/usage_summary" \
+  -X GET \
+  -H "Authorization: bearer [token]"
+```
+
+```
+Example Response
+```
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+<%= yield_content :shared_spaces_usage_summary %>
+```
+
+This endpoint returns the number of bound apps in spaces where the service instance has been shared to.
+
+#### Definition
+`GET /v3/service_instances/:guid/relationships/shared_spaces/usage_summary`
+
+#### Permitted roles (in the service instance's originating space)
+ |
+--- | ---
+Admin |
+Admin Read-Only |
+Global Auditor |
+Org Manager |
+Space Auditor |
+Space Developer |
+Space Manager |

docs/v3/source/index.md

@@ -364,6 +364,7 @@ includes:
   - experimental_resources/service_instances/credentials
   - experimental_resources/service_instances/parameters
   - experimental_resources/service_instances/delete
+  - experimental_resources/service_instances/get_shared_spaces_usage_summary
   - experimental_resources/sidecars/header
   - experimental_resources/sidecars/object
   - experimental_resources/sidecars/create_from_app

spec/request/service_instances_spec.rb

@@ -753,6 +753,90 @@ def check_filtered_instances(*instances)
     end
   end
 
+  describe 'GET /v3/service_instances/:guid/relationships/shared_spaces/usage_summary' do
+    let(:guid) { instance.guid }
+    let(:instance) { VCAP::CloudController::ManagedServiceInstance.make(space: space) }
+    let(:space_1) { VCAP::CloudController::Space.make }
+    let(:space_2) { VCAP::CloudController::Space.make }
+    let(:space_3) { VCAP::CloudController::Space.make }
+    let(:url) { "/v3/service_instances/#{guid}/relationships/shared_spaces/usage_summary" }
+    let(:api_call) { lambda { |user_headers| get url, nil, user_headers } }
+    let(:bindings_on_space_1) { 1 }
+    let(:bindings_on_space_2) { 3 }
+
+    def create_bindings(instance, space:, count:)
+      (1..count).each do
+        VCAP::CloudController::ServiceBinding.make(
+          app: VCAP::CloudController::AppModel.make(space: space),
+          service_instance: instance
+        )
+      end
+    end
+
+    before do
+      share_service_instance(instance, space_1)
+      share_service_instance(instance, space_2)
+      share_service_instance(instance, space_3)
+
+      create_bindings(instance, space: space_1, count: bindings_on_space_1)
+      create_bindings(instance, space: space_2, count: bindings_on_space_2)
+    end
+
+    context 'permissions' do
+      let(:response_object) {
+        {
+          usage_summary: [
+            { space: { guid: space_1.guid }, bound_app_count: bindings_on_space_1 },
+            { space: { guid: space_2.guid }, bound_app_count: bindings_on_space_2 },
+            { space: { guid: space_3.guid }, bound_app_count: 0 }
+          ],
+          links: {
+            self: { href: "#{link_prefix}/v3/service_instances/#{instance.guid}/relationships/shared_spaces/usage_summary" },
+            shared_spaces: { href: "#{link_prefix}/v3/service_instances/#{instance.guid}/relationships/shared_spaces" },
+            service_instance: { href: "#{link_prefix}/v3/service_instances/#{instance.guid}" }
+          }
+        }
+      }
+      let(:usage_summary_response) { { code: 200, response_object: response_object } }
+
+      let(:expected_codes_and_responses) do
+        Hash.new(
+          code: 404,
+          response_objects: []
+        ).tap do |h|
+          h['admin'] = usage_summary_response
+          h['admin_read_only'] = usage_summary_response
+          h['global_auditor'] = usage_summary_response
+          h['space_developer'] = usage_summary_response
+          h['space_manager'] = usage_summary_response
+          h['space_auditor'] = usage_summary_response
+          h['org_manager'] = usage_summary_response
+        end
+      end
+
+      it_behaves_like 'permissions for single object endpoint', ALL_PERMISSIONS
+    end
+
+    context 'when the instance does not exist' do
+      let(:guid) { 'a-fake-guid' }
+      it 'responds with 404 Not Found' do
+        api_call.call(admin_headers)
+        expect(last_response).to have_status_code(404)
+      end
+    end
+
+    context 'when the user cannot read from the originating space' do
+      it 'responds with 404 Not Found' do
+        user = VCAP::CloudController::User.make
+        set_current_user_as_role(role: 'space_developer', org: space_2.organization, space: space_2, user: user)
+
+        api_call.call(headers_for(user))
+
+        expect(last_response).to have_status_code(404)
+      end
+    end
+  end
+
   describe 'POST /v3/service_instances' do
     let(:api_call) { lambda { |user_headers| post '/v3/service_instances', request_body.to_json, user_headers } }
     let(:space_guid) { space.guid }
@@ -3401,41 +3485,6 @@ def enable_sharing!
     let!(:service_instance2) { VCAP::CloudController::ManagedServiceInstance.make(space: space, name: 'redis') }
     let!(:service_instance3) { VCAP::CloudController::ManagedServiceInstance.make(space: another_space, name: 'mysql') }
 
-    describe 'GET /v3/service_instances/:guid/relationships/shared_spaces' do
-      before do
-        share_request = {
-          'data' => [
-            { 'guid' => target_space.guid }
-          ]
-        }
-
-        enable_feature_flag!
-        post "/v3/service_instances/#{service_instance1.guid}/relationships/shared_spaces", share_request.to_json, admin_header
-        expect(last_response.status).to eq(200)
-
-        disable_feature_flag!
-      end
-
-      it 'returns a list of space guids where the service instance is shared to' do
-        set_current_user_as_role(role: 'space_developer', org: space.organization, space: space, user: user)
-
-        get "/v3/service_instances/#{service_instance1.guid}/relationships/shared_spaces", nil, user_header
-
-        expect(last_response.status).to eq(200)
-
-        expected_response = {
-          'data' => [
-            { 'guid' => target_space.guid }
-          ],
-          'links' => {
-            'self' => { 'href' => "#{link_prefix}/v3/service_instances/#{service_instance1.guid}/relationships/shared_spaces" },
-          }
-        }
-
-        expect(parsed_response).to be_a_response_like(expected_response)
-      end
-    end
-
     describe 'POST /v3/service_instances/:guid/relationships/shared_spaces' do
       before do
         VCAP::CloudController::FeatureFlag.make(name: 'service_instance_sharing', enabled: true, error_message: nil)

spec/unit/presenters/v3/shared_spaces_usage_summary_presenter_spec.rb

@@ -0,0 +1,71 @@
+require 'spec_helper'
+require 'presenters/v3/shared_spaces_usage_summary_presenter'
+
+module VCAP::CloudController::Presenters::V3
+  RSpec.describe SharedSpacesUsageSummaryPresenter do
+    let(:presenter) { described_class.new(instance) }
+    let(:result) { presenter.to_hash.deep_symbolize_keys }
+
+    let(:space) { VCAP::CloudController::Space.make }
+    let(:instance) { VCAP::CloudController::ManagedServiceInstance.make(space: space) }
+
+    let(:space_1) { VCAP::CloudController::Space.make }
+    let(:space_2) { VCAP::CloudController::Space.make }
+    let(:space_3) { VCAP::CloudController::Space.make }
+
+    def create_bindings(instance, space:, count:)
+      (1..count).each do
+        VCAP::CloudController::ServiceBinding.make(
+          app: VCAP::CloudController::AppModel.make(space: space),
+          service_instance: instance
+        )
+      end
+    end
+
+    before do
+      instance.add_shared_space(space_1)
+      instance.add_shared_space(space_2)
+      instance.add_shared_space(space_3)
+
+      create_bindings(instance, space: space, count: 2)
+      create_bindings(instance, space: space_1, count: 3)
+      create_bindings(instance, space: space_2, count: 1)
+    end
+
+    it 'presents the usage summary' do
+      expect(result).to eq({
+        usage_summary: [{
+          space: { guid: space_1.guid },
+          bound_app_count: 3
+        }, {
+          space: { guid: space_2.guid },
+          bound_app_count: 1
+        }, {
+          space: { guid: space_3.guid },
+          bound_app_count: 0
+        }],
+        links: {
+          self: { href: "#{link_prefix}/v3/service_instances/#{instance.guid}/relationships/shared_spaces/usage_summary" },
+          shared_spaces: { href: "#{link_prefix}/v3/service_instances/#{instance.guid}/relationships/shared_spaces" },
+          service_instance: { href: "#{link_prefix}/v3/service_instances/#{instance.guid}" }
+        }
+      })
+    end
+
+    context 'when there are no shared spaces' do
+      let(:another_instance) { VCAP::CloudController::ManagedServiceInstance.make(space: space) }
+      let(:presenter) { described_class.new(another_instance) }
+
+      it 'presents an empty usage summary' do
+        expect(result).to eq({
+          usage_summary: [],
+          links: {
+            self: { href: "#{link_prefix}/v3/service_instances/#{another_instance.guid}/relationships/shared_spaces/usage_summary" },
+            shared_spaces: { href: "#{link_prefix}/v3/service_instances/#{another_instance.guid}/relationships/shared_spaces" },
+            service_instance: { href: "#{link_prefix}/v3/service_instances/#{another_instance.guid}" }
+          }
+        })
+      end
+    end
+  end
+end