v3(services): shared_spaces can include fields

Valid fields are:
* space: name, guid, relationships.organization
* space.organization: name, guid

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

Author: Derik Evangelista

app/controllers/v3/service_instances_controller.rb

@@ -6,6 +6,7 @@
 require 'messages/service_instance_create_managed_message'
 require 'messages/service_instance_create_user_provided_message'
 require 'messages/service_instance_show_message'
+require 'messages/shared_spaces_show_message'
 require 'presenters/v3/relationship_presenter'
 require 'presenters/v3/to_many_relationship_presenter'
 require 'presenters/v3/paginated_list_presenter'
@@ -161,8 +162,16 @@ def relationships_shared_spaces
     service_instance = ServiceInstance.first(guid: hashed_params[:service_instance_guid])
     resource_not_found!(:service_instance) unless service_instance && can_read_space?(service_instance.space)
 
+    message = SharedSpacesShowMessage.from_params(query_params)
+    invalid_param!(message.errors.full_messages) unless message.valid?
+
     render status: :ok, json: Presenters::V3::ToManyRelationshipPresenter.new(
-      "service_instances/#{service_instance.guid}", service_instance.shared_spaces, 'shared_spaces', build_related: false)
+      "service_instances/#{service_instance.guid}",
+      service_instance.shared_spaces,
+      'shared_spaces',
+      build_related: false,
+      decorators: decorators_for_fields(message.fields)
+    )
   end
 
   def credentials

app/decorators/field_service_instance_organization_decorator.rb

@@ -12,9 +12,9 @@ def initialize(fields)
       @fields = fields[:'space.organization'].to_set.intersection(self.class.allowed)
     end
 
-    def decorate(hash, service_instances)
+    def decorate(hash, resources)
       hash[:included] ||= {}
-      spaces = service_instances.map(&:space).uniq
+      spaces = resources.map { |r| r.try(:space) || r }.uniq
       orgs = spaces.map(&:organization).uniq
 
       hash[:included][:organizations] = orgs.sort_by(&:created_at).map do |org|

app/decorators/field_service_instance_space_decorator.rb

@@ -12,9 +12,10 @@ def initialize(fields)
       @fields = fields[:space].to_set.intersection(self.class.allowed)
     end
 
-    def decorate(hash, service_instances)
+    def decorate(hash, resources)
       hash[:included] ||= {}
-      spaces = service_instances.map(&:space).uniq
+
+      spaces = resources.map { |r| r.try(:space) || r }.uniq
 
       hash[:included][:spaces] = spaces.sort_by(&:created_at).map do |space|
         temp = {}

app/messages/shared_spaces_show_message.rb

@@ -0,0 +1,18 @@
+module VCAP::CloudController
+  class SharedSpacesShowMessage < BaseMessage
+    register_allowed_keys [:fields]
+
+    validates_with NoAdditionalParamsValidator
+    validates :fields, allow_nil: true, fields: {
+      allowed: {
+        'space' => %w(name guid relationships.organization),
+        'space.organization' => %w(name guid)
+      }
+    }
+
+    def self.from_params(params)
+      instance = super(params, [], fields: %w(fields))
+      instance
+    end
+  end
+end

app/presenters/v3/to_many_relationship_presenter.rb

@@ -4,18 +4,22 @@ module VCAP::CloudController
   module Presenters
     module V3
       class ToManyRelationshipPresenter < BasePresenter
-        def initialize(relation_url, relationships, relationship_path, build_related: true)
+        def initialize(relation_url, relationships, relationship_path, build_related: true, decorators: [])
           @relation_url = relation_url
           @relationships = relationships
           @relationship_path = relationship_path
           @build_related = build_related
+          @decorators = decorators
         end
 
         def to_hash
-          {
-            data: build_relations,
+          relations = build_relations
+          h = {
+            data: relations,
             links: build_links
           }
+
+          @decorators.reduce(h) { |memo, d| d.decorate(memo, @relationships) }
         end
 
         private

docs/v3/source/includes/concepts/_fields.md.erb

@@ -30,6 +30,7 @@ For information on `fields` support for each resource refer to its documentation
 Resource |  Endpoint
 -------- | --------------
 **Service Instances** | [v3/service_instances](#list-service-instances), [v3/service_instances/:guid](/#get-a-service-instance)
+**Shared Spaces** | [/v3/service_instances/:guid/relationships/shared_spaces](#list-shared-spaces-relationship)
 **Service Offerings** | [v3/service_offerings](#list-service-offerings), [v3/service_offerings/:guid](/#get-a-service-offering)
 **Service Plans** | [v3/service_plans](#list-service-plans), [v3/service_plans/:guid](/#get-a-service-plan)
 

docs/v3/source/includes/resources/service_instances/_list_shared_spaces.md.erb

@@ -25,6 +25,19 @@ This endpoint lists the spaces that the service instance has been shared to.
 #### Definition
 `GET /v3/service_instances/:guid/relationships/shared_spaces`
 
+#### Query parameters
+
+Name | Type | Description
+---- | ---- | ------------
+**fields** (*experimental*)| [_fields parameter_](#fields-parameter) | [_Allowed values_](#shared-spaces-fields)
+
+##### Shared Spaces List Fields
+
+Resource            | Allowed Keys
+------------------- | ----
+space | `guid`, `name`, `relationships.organization`
+space.organization| `guid`, `name`
+
 #### Permitted roles (in the service instance's originating space)
  |
 --- | ---

spec/request/service_instances_spec.rb

@@ -660,6 +660,99 @@ def check_filtered_instances(*instances)
     end
   end
 
+  describe 'GET /v3/service_instances/:guid/relationships/shared_spaces' do
+    let(:user_header) { headers_for(user) }
+    let(:instance) { VCAP::CloudController::ManagedServiceInstance.make(space: space) }
+    let(:other_space) { VCAP::CloudController::Space.make }
+
+    before(:each) do
+      share_service_instance(instance, other_space)
+    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/#{instance.guid}/relationships/shared_spaces", nil, user_header
+      expect(last_response.status).to eq(200)
+
+      expected_response = {
+        data: [{ guid: other_space.guid }],
+        links: {
+          self: { href: "#{link_prefix}/v3/service_instances/#{instance.guid}/relationships/shared_spaces" },
+        }
+      }.with_indifferent_access
+
+      expect(parsed_response).to be_a_response_like(expected_response)
+    end
+
+    it 'respond with 404 when the user cannot read the originating space' do
+      set_current_user_as_role(role: 'space_developer', org: other_space.organization, space: other_space, user: user)
+      get "/v3/service_instances/#{instance.guid}/relationships/shared_spaces", nil, user_header
+      expect(last_response.status).to eq(404)
+    end
+
+    describe 'fields' do
+      it 'can include the space name, guid and organization relationship fields' do
+        get "/v3/service_instances/#{instance.guid}/relationships/shared_spaces?fields[space]=name,guid,relationships.organization", nil, admin_headers
+        expect(last_response).to have_status_code(200)
+
+        r = { organization: { data: { guid: other_space.organization.guid } } }
+        included = {
+          spaces: [
+            { name: other_space.name, guid: other_space.guid, relationships: r }
+          ]
+        }
+
+        expect({ included: parsed_response['included'] }).to match_json_response({ included: included })
+      end
+
+      it 'can include the organization name and guid fields through space' do
+        get "/v3/service_instances/#{instance.guid}/relationships/shared_spaces?fields[space.organization]=name,guid", nil, admin_headers
+        expect(last_response).to have_status_code(200)
+
+        included = {
+          organizations: [
+            {
+              name: other_space.organization.name,
+              guid: other_space.organization.guid
+            }
+          ]
+        }
+
+        expect({ included: parsed_response['included'] }).to match_json_response({ included: included })
+      end
+
+      it 'fails for invalid resources' do
+        get "/v3/service_instances/#{instance.guid}/relationships/shared_spaces?fields[fruit]=name", nil, admin_headers
+        expect(last_response).to have_status_code(400)
+        expect(parsed_response['errors']).to include(
+          include(
+            'detail' => "The query parameter is invalid: Fields [fruit] valid resources are: 'space', 'space.organization'"
+          )
+        )
+      end
+
+      it 'fails for not allowed space fields' do
+        get "/v3/service_instances/#{instance.guid}/relationships/shared_spaces?fields[space]=metadata", nil, admin_headers
+        expect(last_response).to have_status_code(400)
+        expect(parsed_response['errors']).to include(
+          include(
+            'detail' => "The query parameter is invalid: Fields valid keys for 'space' are: 'name', 'guid', 'relationships.organization'"
+          )
+        )
+      end
+
+      it 'fails for not allowed space.organization fields' do
+        get "/v3/service_instances/#{instance.guid}/relationships/shared_spaces?fields[space.organization]=metadata", nil, admin_headers
+        expect(last_response).to have_status_code(400)
+        expect(parsed_response['errors']).to include(
+          include(
+            'detail' => "The query parameter is invalid: Fields valid keys for 'space.organization' are: 'name', 'guid'"
+          )
+        )
+      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 }

spec/unit/decorators/field_service_instance_organization_decorator_spec.rb

@@ -68,6 +68,27 @@ module VCAP::CloudController
           expect(hash[:included][:organizations]).to have(1).element
         end
       end
+
+      context 'decorating relationships' do
+        it 'includes the related resource correctly' do
+          decorator = described_class.new({ 'space.organization': ['name', 'guid'] })
+          undecorated_hash = { foo: 'bar', included: { monkeys: %w(zach greg) } }
+          relationship = [space1, space2, space1]
+
+          hash = decorator.decorate(undecorated_hash, relationship)
+
+          expect(hash).to match({
+            foo: 'bar',
+            included: {
+              monkeys: %w(zach greg),
+              organizations: [
+                { name: org1.name, guid: org1.guid },
+                { name: org2.name, guid: org2.guid }
+              ]
+            }
+          })
+        end
+      end
     end
 
     describe '.match?' do

spec/unit/decorators/field_service_instance_space_decorator_spec.rb

@@ -144,6 +144,31 @@ module VCAP::CloudController
           expect(hash[:included][:spaces]).to have(1).element
         end
       end
+
+      context 'decorating relationships' do
+        it 'includes the related resource correctly' do
+          decorator = described_class.new({ 'space': ['guid'] })
+          undecorated_hash = { foo: 'bar', included: { monkeys: %w(zach greg) } }
+          relationship = [space1, space2, space1]
+
+          hash = decorator.decorate(undecorated_hash, relationship)
+
+          expect(hash).to match({
+            foo: 'bar',
+            included: {
+              monkeys: %w(zach greg),
+              spaces: [
+                {
+                  guid: space1.guid,
+                },
+                {
+                  guid: space2.guid,
+                }
+              ]
+            }
+          })
+        end
+      end
     end
 
     describe '.match?' do