Introduce strategy parameter for binding creation

Add optional strategy parameter (single | multiple) to the binding
creation API. Allow multiple bindings when strategy = "multiple" and
max_service_credential_bindings_per_app_service_instance is greater than
1.

Author: philippthun

app/actions/service_credential_binding_app_create.rb

@@ -48,7 +48,7 @@ def precursor(service_instance, message:, app: nil, volume_mount_services_enable
               num_valid_bindings += 1
             end
 
-            validate_number_of_bindings!(num_valid_bindings)
+            validate_number_of_bindings!(num_valid_bindings, strategy: message.strategy)
             validate_app_guid_name_uniqueness!(app.guid, message.name, service_instance.guid)
 
             new_binding.save_with_attributes_and_new_operation(
@@ -82,8 +82,12 @@ def validate_binding!(binding, desired_binding_name:)
         name_cannot_be_changed! if binding.name != desired_binding_name
       end
 
-      def validate_number_of_bindings!(number_of_bindings)
-        too_many_bindings! if number_of_bindings >= max_bindings_per_app_service_instance
+      def validate_number_of_bindings!(number_of_bindings, strategy:)
+        if strategy == 'multiple'
+          too_many_bindings! if number_of_bindings >= max_bindings_per_app_service_instance
+        elsif number_of_bindings >= 1
+          already_bound!
+        end
       end
 
       def validate_app_guid_name_uniqueness!(target_app_guid, desired_binding_name, target_service_instance_guid)

app/messages/service_credential_app_binding_create_message.rb

@@ -1,5 +1,10 @@
 module VCAP::CloudController
   class ServiceCredentialAppBindingCreateMessage < ServiceCredentialBindingCreateMessage
+    validates :strategy, allow_blank: false, allow_nil: true, inclusion: {
+      in: %w[single multiple],
+      message: "must be 'single' or 'multiple'"
+    }
+
     def relationships_message
       @relationships_message ||= Relationships.new(relationships&.deep_symbolize_keys)
     end

app/messages/service_credential_binding_create_message.rb

@@ -1,7 +1,7 @@
 require 'messages/metadata_base_message'
 module VCAP::CloudController
   class ServiceCredentialBindingCreateMessage < MetadataBaseMessage
-    register_allowed_keys %i[type name relationships parameters]
+    register_allowed_keys %i[type strategy name relationships parameters]
     validates_with NoAdditionalKeysValidator, RelationshipValidator
     validates :parameters, hash: true, allow_nil: true
     validates :type, allow_blank: false, inclusion: {

docs/v3/source/includes/resources/service_credential_bindings/_create.md.erb

@@ -116,6 +116,7 @@ Name | Type | Description
 Name | Type | Description |
 ---- | ---- | ----------- |
 **relationships.app** | [_to-one relationship_](#to-one-relationships) | The app to be bound. Required when type is `app`
+**strategy** | string | Strategy for creating the service credential binding. Valid values are `single` (default) and `multiple` (experimental). Only valid when type is `app`.
 **parameters** | _object_ | A JSON object that is passed to the service broker
 **metadata.labels** | [_label object_](#labels) | Labels applied to the service credential binding
 **metadata.annotations**  | [_annotation object_](#annotations) | Annotations applied to the service credential binding

docs/v3/source/includes/resources/service_credential_bindings/_header.md

@@ -4,9 +4,8 @@ Service credential bindings are used to make the details of the connection to a
 
 Service credential bindings can be of type `app` or `key`.
 
-A service credential binding is of type `app` when it is a binding between a [service instance](#service-instances) and an [application](#apps)
+A service credential binding is of type `app` when it is a binding between a [service instance](#service-instances) and an [application](#apps).
 Not all services support this binding, as some services deliver value to users directly without integration with an application. 
 Field `broker_catalog.features.bindable` from [service plan](#the-service-plan-object) of the service instance can be used to determine if it is bindable.
 
 A service credential binding is of type `key` when it only retrieves the details of the service instance and makes them available to the developer. 
-

spec/unit/actions/service_credential_binding_app_create_spec.rb

@@ -190,6 +190,7 @@ module V3
           end
 
           context 'when multiple bindings are allowed' do
+            let(:message) { VCAP::CloudController::ServiceCredentialAppBindingCreateMessage.new({ name: name, strategy: 'multiple' }) }
             let(:binding_1) { ServiceBinding.make(service_instance:, app:, name:) }
             let(:binding_2) { ServiceBinding.make(service_instance:, app:, name:) }
 
@@ -276,6 +277,16 @@ module V3
                                    'The app has too many bindings to this service instance (limit: 2). Consider deleting existing/orphaned bindings.')
               end
             end
+
+            context "when the strategy = 'multiple' parameter is omitted" do
+              let(:message) { VCAP::CloudController::ServiceCredentialAppBindingCreateMessage.new({ name: }) }
+
+              it 'raises an error' do
+                expect do
+                  action.precursor(service_instance, app:, message:)
+                end.to raise_error(ServiceCredentialBindingAppCreate::UnprocessableCreate, 'The app is already bound to the service instance')
+              end
+            end
           end
         end
 

spec/unit/messages/service_credential_app_binding_create_message_spec.rb

@@ -8,6 +8,7 @@ module VCAP::CloudController
     let(:params) do
       {
         type: 'app',
+        strategy: 'single',
         name: 'some-name',
         parameters: {
           some_param: 'very important',
@@ -26,6 +27,7 @@ module VCAP::CloudController
       it 'builds a valid ServiceCredentialBindingCreateMessage' do
         expect(message).to be_valid
         expect(message.type).to eq('app')
+        expect(message.strategy).to eq('single')
         expect(message.name).to eq('some-name')
         expect(message.service_instance_guid).to eq('some-instance-guid')
         expect(message.app_guid).to eq('some-app-guid')
@@ -58,6 +60,20 @@ module VCAP::CloudController
         end
       end
 
+      context 'strategy' do
+        it 'accepts single and multiple' do
+          %w[single multiple].each do |strategy|
+            params[:strategy] = strategy
+            expect(subject.new(params)).to be_valid
+          end
+        end
+
+        it 'is invalid with any other value' do
+          params[:strategy] = 'test'
+          expect(subject.new(params)).not_to be_valid
+        end
+      end
+
       context 'name' do
         it 'accepts empty' do
           params[:name] = ''

spec/unit/messages/service_credential_binding_create_message_spec.rb

@@ -8,6 +8,7 @@ module VCAP::CloudController
     let(:params) do
       {
         type: 'app',
+        strategy: 'single',
         name: 'some-name',
         parameters: {
           some_param: 'very important',
@@ -29,6 +30,7 @@ module VCAP::CloudController
       it 'builds a valid ServiceCredentialBindingCreateMessage' do
         expect(message).to be_valid
         expect(message.type).to eq('app')
+        expect(message.strategy).to eq('single')
         expect(message.name).to eq('some-name')
         expect(message.service_instance_guid).to eq('some-instance-guid')
         expect(message.parameters).to eq({ some_param: 'very important', another_param: 'epa' })