Introduce per-route options

This commit adds a configurable load-balancing algorithm as a first example of per-route options.
It adds the 'options' field to the route object in the V3 API, and the app manifest.
The options field is an object storing key-value pairs, with 'lb_algo' being the only supported key for now.
The supported load-balancing algorithms are 'round-robin' and 'least-connections'.
The options field is introduced as a column in the database route table, and forwarded to the Diego backend.

Co-authored-by: Alexander Nicke <[email protected]>
See: cloudfoundry/capi-release#482
See: https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0027-generic-per-route-features.md

Author: a18e

app/actions/manifest_route_update.rb

@@ -1,5 +1,6 @@
 require 'cloud_controller/app_manifest/manifest_route'
 require 'actions/route_create'
+require 'actions/route_update'
 
 module VCAP::CloudController
   class ManifestRouteUpdate
@@ -81,7 +82,8 @@ def find_or_create_valid_route(app, manifest_route, user_audit_info)
             message = RouteCreateMessage.new({
                                                'host' => host,
                                                'path' => manifest_route[:path],
-                                               'port' => manifest_route[:port]
+                                               'port' => manifest_route[:port],
+                                               'options' => manifest_route[:options]
                                              })
 
             route = RouteCreate.new(user_audit_info).create(
@@ -90,6 +92,12 @@ def find_or_create_valid_route(app, manifest_route, user_audit_info)
               domain: existing_domain,
               manifest_triggered: true
             )
+          elsif route[:options] != manifest_route[:options]
+            message = RouteUpdateMessage.new({
+                                               'options' => manifest_route[:options]
+                                             })
+            route = RouteUpdate.new.update(route:, message:)
+
           elsif route.space.guid != app.space_guid
             raise InvalidRoute.new('Routes cannot be mapped to destinations in different spaces')
           end

app/actions/route_create.rb

@@ -15,7 +15,8 @@ def create(message:, space:, domain:, manifest_triggered: false)
         path: message.path || '',
         port: port(message, domain),
         space: space,
-        domain: domain
+        domain: domain,
+        options: message.options
       )
 
       Route.db.transaction do

app/actions/route_update.rb

@@ -2,6 +2,16 @@ module VCAP::CloudController
   class RouteUpdate
     def update(route:, message:)
       Route.db.transaction do
+        if message.requested?(:options)
+          route.options = if message.options.nil?
+                            nil
+                          elsif route.options.nil?
+                            message.options
+                          else
+                            route.options.merge(message.options)
+                          end
+        end
+        route.save
         MetadataUpdate.update(route, message)
       end
 

app/messages/manifest_routes_update_message.rb

@@ -1,4 +1,5 @@
 require 'messages/base_message'
+require 'messages/route_options_message'
 require 'cloud_controller/app_manifest/manifest_route'
 
 module VCAP::CloudController
@@ -7,9 +8,20 @@ class ManifestRoutesUpdateMessage < BaseMessage
 
     class ManifestRoutesYAMLValidator < ActiveModel::Validator
       def validate(record)
-        return unless is_not_array?(record.routes) || contains_non_route_hash_values?(record.routes)
+        if is_not_array?(record.routes) || contains_non_route_hash_values?(record.routes)
+          record.errors.add(:routes, message: 'must be a list of route objects')
+          return
+        end
 
-        record.errors.add(:routes, message: 'must be a list of route objects')
+        if contains_invalid_route_options?(record.routes)
+          record.errors.add(:routes, message: 'contains invalid route options')
+          return
+        end
+
+        return unless contains_invalid_lb_algo?(record.routes)
+
+        record.errors.add(:routes, message: 'contains an invalid loadbalancing-algorithm option')
+        nil
       end
 
       def is_not_array?(routes)
@@ -19,6 +31,26 @@ def is_not_array?(routes)
       def contains_non_route_hash_values?(routes)
         routes.any? { |r| !(r.is_a?(Hash) && r[:route].present?) }
       end
+
+      def contains_invalid_route_options?(routes)
+        routes.any? do |r|
+          next unless r[:options]
+
+          return true unless r[:options].is_a?(Hash)
+
+          return false if r[:options].empty?
+
+          return r[:options].keys.all? { |key| RouteOptionsMessage::VALID_MANIFEST_ROUTE_OPTIONS.exclude?(key) }
+        end
+      end
+
+      def contains_invalid_lb_algo?(routes)
+        routes.any? do |r|
+          next unless r[:options] && r[:options][:'loadbalancing-algorithm']
+
+          return true if r[:options][:'loadbalancing-algorithm'] && RouteOptionsMessage::VALID_LOADBALANCING_ALGORITHMS.exclude?(r[:options][:'loadbalancing-algorithm'])
+        end
+      end
     end
 
     validates_with NoAdditionalKeysValidator
@@ -32,10 +64,12 @@ def contains_non_route_hash_values?(routes)
 
     def manifest_route_mappings
       @manifest_route_mappings ||= routes.map do |route|
-        {
-          route: ManifestRoute.parse(route[:route]),
+        r = {
+          route: ManifestRoute.parse(route[:route], route[:options]),
           protocol: route[:protocol]
         }
+        r[:options] = route[:options] unless route[:options].nil?
+        r
       end
     end
 

app/messages/route_create_message.rb

@@ -1,4 +1,5 @@
 require 'messages/metadata_base_message'
+require 'messages/route_options_message'
 
 module VCAP::CloudController
   class RouteCreateMessage < MetadataBaseMessage
@@ -10,6 +11,7 @@ class RouteCreateMessage < MetadataBaseMessage
       path
       port
       relationships
+      options
     ]
 
     validates :host,
@@ -56,6 +58,7 @@ class RouteCreateMessage < MetadataBaseMessage
 
     validates_with NoAdditionalKeysValidator
     validates_with RelationshipValidator
+    validates_with OptionsValidator
 
     delegate :space_guid, to: :relationships_message
     delegate :domain_guid, to: :relationships_message
@@ -65,6 +68,10 @@ def relationships_message
       @relationships_message ||= Relationships.new(relationships&.deep_symbolize_keys)
     end
 
+    def options_message
+      @options_message ||= RouteOptionsMessage.new(options&.deep_symbolize_keys)
+    end
+
     def wildcard?
       host == '*'
     end

app/messages/route_options_message.rb

@@ -0,0 +1,16 @@
+require 'messages/metadata_base_message'
+
+module VCAP::CloudController
+  class RouteOptionsMessage < BaseMessage
+    VALID_MANIFEST_ROUTE_OPTIONS = %i[loadbalancing-algorithm].freeze
+    VALID_ROUTE_OPTIONS = %i[lb_algo].freeze
+    VALID_LOADBALANCING_ALGORITHMS = %w[round-robin least-connections].freeze
+
+    register_allowed_keys %i[lb_algo]
+    validates_with NoAdditionalKeysValidator
+    validates :lb_algo,
+              inclusion: { in: VALID_LOADBALANCING_ALGORITHMS, message: "'%<value>s' is not a supported load-balancing algorithm" },
+              presence: true,
+              allow_nil: true
+  end
+end

app/messages/route_update_message.rb

@@ -1,8 +1,19 @@
 require 'messages/metadata_base_message'
+require 'messages/route_options_message'
 
 module VCAP::CloudController
   class RouteUpdateMessage < MetadataBaseMessage
-    register_allowed_keys []
+    register_allowed_keys %i[options]
+
+    def self.options_requested?
+      @options_requested ||= proc { |a| a.requested?(:options) }
+    end
+
+    def options_message
+      @options_message ||= RouteOptionsMessage.new(options&.deep_symbolize_keys)
+    end
+
+    validates_with OptionsValidator, if: options_requested?
 
     validates_with NoAdditionalKeysValidator
   end

app/messages/validators.rb

@@ -240,6 +240,26 @@ def validate(record)
     end
   end
 
+  class OptionsValidator < ActiveModel::Validator
+    def validate(record)
+      # Empty option hashes are allowed, so we skip further validation
+      record.options.blank? && return
+
+      unless record.options.is_a?(Hash)
+        record.errors.add(:options, message: "'options' is not a valid object")
+        return
+      end
+
+      opt = record.options_message
+
+      return if opt.valid?
+
+      opt.errors.full_messages.each do |message|
+        record.errors.add(:options, message:)
+      end
+    end
+  end
+
   class ToOneRelationshipValidator < ActiveModel::EachValidator
     def validate_each(record, attribute, relationship)
       if has_correct_structure?(relationship)

app/models/runtime/route.rb

@@ -40,8 +40,8 @@ class OutOfVIPException < CloudController::Errors::InvalidRelation; end
 
     add_association_dependencies route_mappings: :destroy
 
-    export_attributes :host, :path, :domain_guid, :space_guid, :service_instance_guid, :port
-    import_attributes :host, :path, :domain_guid, :space_guid, :app_guids, :port
+    export_attributes :host, :path, :domain_guid, :space_guid, :service_instance_guid, :port, :options
+    import_attributes :host, :path, :domain_guid, :space_guid, :app_guids, :port, :options
 
     add_association_dependencies labels: :destroy
     add_association_dependencies annotations: :destroy
@@ -71,6 +71,23 @@ def as_summary_json
       }
     end
 
+    def options_with_serialization=(opts)
+      self.options_without_serialization = Oj.dump(opts)
+    end
+
+    alias_method :options_without_serialization=, :options=
+    alias_method :options=, :options_with_serialization=
+
+    def options_with_serialization
+      string = options_without_serialization
+      return nil if string.blank?
+
+      Oj.load(string)
+    end
+
+    alias_method :options_without_serialization, :options
+    alias_method :options, :options_with_serialization
+
     alias_method :old_path, :path
     def path
       old_path.nil? ? '' : old_path

app/presenters/v3/app_manifest_presenters/route_properties_presenter.rb

@@ -5,10 +5,17 @@ module AppManifestPresenters
         class RoutePropertiesPresenter
           def to_hash(route_mappings:, app:, **_)
             route_hashes = route_mappings.map do |route_mapping|
-              {
+              route_hash = {
                 route: route_mapping.route.uri,
                 protocol: route_mapping.protocol
               }
+
+              if route_mapping.route.options
+                route_hash[:options] = {}
+                route_hash[:options][:'loadbalancing-algorithm'] = route_mapping.route.options[:lb_algo] if route_mapping.route.options[:lb_algo]
+              end
+
+              route_hash
             end
 
             { routes: alphabetize(route_hashes).presence }