Support Hash-Based Routing #4746

hoffmaen · 2026-01-09T17:17:03Z

This Pull-Request replaces #4696.

This Pull-Request adds support for hash-based routing to Cloud Controller.

Summary:
The routes model is enhanced as follows:

hash is added as a valid loadbalancing option
hash_header is added as a per-route option. The option is mandatory when loadbalancing=hash
hash_balance is added as a per-route option. The option is optional when loadbalancing=hash

Validation of these options is added when creating and updating both via API and via manifest. All validations that do not need the context of a potentially existing route during an update, are executed in the message:

Hash Balance must be numeric
Hash Header and Hash Balance must not be specified together with round-robin or least-connection
Values for Hash Header and Hash Balance must not be arbitrarily long

Further validations and cleanups are performed on the route model, as they need the context of existing routes:

The route options from the update message are merged with existing routes, when existing
When the loadbalancing algorithm is hash, then Hash Header must be specified
When the loadbalancing algorithm is switched from hash to something else (or when it is removed), also Hash Header and Hash Balance options are removed
Hash Balance is always stored as a string, and is always trimmed to a numeric value with one decimal place

The route options are still stored as a raw JSON string in the routes table.

Links:

Thanks for contributing to cloud_controller_ng. To speed up the process of reviewing your pull request please provide us with:

A short explanation of the proposed change:
An explanation of the use cases your change solves
Links to any other associated PRs
I have reviewed the contributing guide
I have viewed, signed, and submitted the Contributor License Agreement
I have made this pull request to the main branch
I have run all the unit tests using bundle exec rake
I have run CF Acceptance Tests

…dations

…ute_options_message

philippthun

Most comments are minor things...

There is a file test-manifest-roundrobin.yml which seems to be some leftover.

I don't think we should modify spec/unit/messages/validators_spec.rb. I see that this was already done for the other route options, but from my point of view this file is more for generic validators and not for specific ones. The tests should be moved into a file route_options_message_spec.rb.

philippthun · 2026-01-12T16:24:58Z

app/messages/manifest_routes_update_message.rb

+    def validate_route_hash_balance_numeric(route, hash_balance)
+      balance_float = Float(hash_balance)
+      # Must be either 0 or >= 1.1 and <= 10.0
+      errors.add(:base, message: "Route '#{route[:route]}': Hash balance must be either 0 or between to 1.1 and 10.0") unless balance_float == 0 || balance_float.between?(1.1, 10)


Suggested change

errors.add(:base, message: "Route '#{route[:route]}': Hash balance must be either 0 or between to 1.1 and 10.0") unless balance_float == 0 || balance_float.between?(1.1, 10)

errors.add(:base, message: "Route '#{route[:route]}': Hash balance must be either 0 or between 1.1 and 10.0") unless balance_float == 0 || balance_float.between?(1.1, 10)

philippthun · 2026-01-12T16:28:45Z

app/messages/manifest_routes_update_message.rb

+      false
+    rescue ArgumentError, TypeError
+      errors.add(:base, message: "Route '#{route[:route]}': Hash balance must be a numeric value")
+      false


Shouldn't this be true (and also in case the error above is added) - my understanding is that true means that the validation found something is further checks are omitted.

philippthun · 2026-01-13T11:15:47Z

app/actions/route_create.rb

+    end

-      error!("Reserved route ports quota exceeded for space '#{space.name}'.") if error.errors.on(:space)&.include?(:total_reserved_route_ports_exceeded)
+    def check_domain_errors!(error, space, domain)


To be consistent with the other methods, this should be validation_error_domain!.

philippthun · 2026-01-13T11:18:49Z

app/actions/route_create.rb

+      error!("Invalid domain. Domain '#{domain.name}' is not available in organization '#{space.organization.name}'.")
+    end

+    def check_quota_errors!(error, space)


To be consistent with the other methods, this should be validation_error_quota!.

philippthun · 2026-01-13T11:20:21Z

app/actions/route_create.rb

-      validation_error_host!(error, host, domain)
-      validation_error_path!(error, host, path, domain)
-      validation_error_port!(error, host, port, domain)
+    def check_route_errors!(error)


To be consistent with the other methods, this should be validation_error_route! or validation_error_route_options!.

philippthun · 2026-01-13T11:20:52Z

app/actions/route_create.rb

+      return unless error.errors.on(:route)&.include?(:hash_header_missing)

-      error!(error.message)
+      error!('Hash header must be present when loadbalancing is set to hash')


All other error messages have a . at the end.

philippthun · 2026-01-13T11:23:22Z

app/actions/route_update.rb

+
+    def validation_error!(error)
+      # Handle hash_header validation error for hash loadbalancing
+      raise Error.new('Hash header must be present when loadbalancing is set to hash') if error.errors.on(:route)&.include?(:hash_header_missing)


Also a . at the end of the message.

philippthun · 2026-01-13T11:30:17Z

app/messages/manifest_routes_update_message.rb

+    def validate_route_hash_options_with_loadbalancing(route, loadbalancing, hash_header, hash_balance)
+      # When loadbalancing is explicitly set to non-hash value, hash options are not allowed
+      if hash_header.present? && loadbalancing.present? && loadbalancing != 'hash'
+        errors.add(:base, message: "Route '#{route[:route]}': Hash header can only be set when loadbalancing is hash")


Maybe add a return to only show one error at a time?

philippthun · 2026-01-13T11:45:19Z

app/messages/route_options_message.rb

+    def self.valid_route_options
+      options = %i[loadbalancing]
+      options += %i[hash_header hash_balance] if VCAP::CloudController::FeatureFlag.enabled?(:hash_based_routing)
+      options.freeze


The freeze is not really necessary (same below for algorithms).

philippthun · 2026-01-13T12:19:40Z

spec/unit/messages/manifest_routes_update_message_spec.rb

+            end
+          end
+
+          context 'when a route contains hash_balance exactly 16 characters' do


The description does not seem to match the tested conditions...

hoffmaen added 30 commits December 16, 2025 17:22

Add loadbalancing option hash, and hash_header/hash_balance. Add vali…

2c8e854

…dations

Add basic options validation to manifest_routes_update_message

9d751e4

Add basic tests for manifest route updates

a8e3b88

Simplify validations, improve error messages, adjust tests

1e63c79

Add validation for hash balance being a float

0371984

Have consistent validations in manifest_routes_updates_message and ro…

afd8569

…ute_options_message

Minor refactoring

41fb78a

Add check for hash_balance value being 0 or >=1.1

16e66df

Transform hash_balance to string in the route model before saving

a7a8862

Validate the route merged with the route update from the message.

42b01f3

Attempt to forward errors in route_update validation to the client

dfde6ec

Add route options changes to app event

0710ef1

Add new hash options to mnifest route

6676cf0

Add new hash options to route properties presenter

bc90e06

Move additional validation to route model

3edb661

Move final options cleanup to route model

9bf2395

Proper error validation and forwarding

9d60a3e

Forward proper error message on route updates

1a4b35b

Add some logging to find the manifest issue

0dddc1d

Add more logging

7b0f56c

Logging in app_manifest_message

981e130

Test a few things

308173e

Test a few things pt 2

c93cbaa

Test a few things pt 3

ed35a67

Test a few things pt 4

e3cffab

Test a few things pt 5

7379cff

Test a few things pt 6

9eec93c

Cleanup logging

4eb3b36

Use symbolized_keys in route_update

69a3ffe

WIP

b3f631f

hoffmaen added 4 commits January 9, 2026 16:46

Add more validations and tests

cde7879

Add more tests for route_update

3e414e9

Add more tests

7373fe2

Some test fixes and cleanup

335b910

hoffmaen mentioned this pull request Jan 9, 2026

Support Hash-Based Routing #4696

Closed

5 tasks

hoffmaen added 4 commits January 9, 2026 21:10

Use blank? instead of nil? for loadbalancing check

0c7c747

Fix rubocop issues

e293c12

Fix rubocop spec issues

9589e16

Refactor to resolve rubocop complexity findings

d39f0a3

philippthun reviewed Jan 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Support Hash-Based Routing #4746

Support Hash-Based Routing #4746

Uh oh!

hoffmaen commented Jan 9, 2026 •

edited

Loading

Uh oh!

philippthun left a comment

Uh oh!

philippthun Jan 12, 2026

Uh oh!

philippthun Jan 12, 2026

Uh oh!

philippthun Jan 13, 2026

Uh oh!

philippthun Jan 13, 2026

Uh oh!

philippthun Jan 13, 2026

Uh oh!

philippthun Jan 13, 2026

Uh oh!

philippthun Jan 13, 2026

Uh oh!

philippthun Jan 13, 2026

Uh oh!

philippthun Jan 13, 2026

Uh oh!

philippthun Jan 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	errors.add(:base, message: "Route '#{route[:route]}': Hash balance must be either 0 or between to 1.1 and 10.0") unless balance_float == 0 \|\| balance_float.between?(1.1, 10)
	errors.add(:base, message: "Route '#{route[:route]}': Hash balance must be either 0 or between 1.1 and 10.0") unless balance_float == 0 \|\| balance_float.between?(1.1, 10)

Support Hash-Based Routing #4746

Are you sure you want to change the base?

Support Hash-Based Routing #4746

Uh oh!

Conversation

hoffmaen commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

philippthun left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

hoffmaen commented Jan 9, 2026 •

edited

Loading