#1672 Custom Default Version Policy (#1673)

* feature written, tests passed

* actualy passes almost all the test.

* resolve conflict, hopefully.

* please.

* let it cook.

* uses constants instead of string for version policies.

* conflict res

* swapped downstream method and version.

* #1731 Read the Docs configuration file v2 (#1733)

* fixing the documentation, using Release/20.0 as base branch

* using latest conf.py, created with sphinx-quickstart, fixing the warnings during documentation generation

* Update .readthedocs.yaml

* switching to threemammals.org for copyright

* adding requirements file, updating readthedocs.yaml, adding formats pdf / epub and config for requirements file

* fixing code block in websockets.rst

* ok, now it should be fine...

* Update kubernetes.rst: Review and fix markup code

* Update websockets.rst: Review and fix markup

* Update conf.py: Update release, author and copyright

---------

Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com>

* * When using the QoS option "ExceptionsAllowedBeforeBreaking" the circuit breaker never opens the circuit.

* merge issue, PortFinder

* some code improvements, using httpresponsemessage status codes as a base for circuit breaker

* Adding more unit tests, and trying to mitigate the test issues with the method "GivenThereIsAPossiblyBrokenServiceRunningOn"

* fixing some test issues

* setting timeout value to 5000 to avoid side effects

* again timing issues

* timing issues again

* ok, first one ok

* Revert "ok, first one ok"

This reverts commit 2e4a673.

* inline method

* putting back logging for http request exception

* removing logger configuration, back to default

* adding a bit more tests to check the policy wrap

* Removing TimeoutStrategy from parameters, it's set by default to pessimistic, at least one policy will be returned, so using First() in circuit breaker and removing the branch Policy == null from delegating handler.

* Fix StyleCop warnings

* Format parameters

* Sort usings

* since we might have two policies wrapped,  timeout and circuit breaker, we can't use the name CircuitBreaker for polly qos provider, it's not right. Using PollyPolicyWrapper and AsnycPollyPolicy instead.

* modifying circuit breaker delegating handler name, usin Polly policies instead

* renaming CircuitBreakerFactory to PolicyWrapperFactory in tests

* DRY for FileConfiguration, using FileConfigurationFactory

* Add copy constructor

* Refactor setup

* Use expression body for method

* Fix acceptance test

* IDE1006 Naming rule violation: These words must begin with upper case characters

* CA1816 Change ReturnsErrorTests.Dispose() to call GC.SuppressFinalize(object)

* Sort usings

* Use expression body for method

* Return back named arguments

---------

Co-authored-by: raman-m <dotnet044@gmail.com>

* feature written, tests passed

* actualy passes almost all the test.

* resolve conflict, hopefully.

* missed this one.

* please.

* come on...

* let it build.

* let it cook.

* copied from main branch.

* conflict res

* resolving conflicts.

* another attempt.

* lf

* re-incorporate downstream version policy.

* renamed the version policies and added acceptance tests.

* trust the dotnet dev cert.

* accepts cert from dotnet.

* Fix compiling errors

* Refactor tests

* a bit of code cleanup, removing some usings

* a bit more cleanup in fileroute

* try and error with the tests

* "Yahoo!...", said @ibnuda :)

* FileRoute: let it go...
Binary copy! :LoL:

* FileRoute: let it cook...
Re-add sweet props

* `dotnet dev-certs` for the `build` job

* Recover `kubernetes.rst`

* docs/make.bat original version

* OcelotBuilderExtensions

* original src/Ocelot.Provider.Polly/v7/PollyPolicyWrapper.cs

* `IVersionPolicyCreator` XML docs

* Code review by @raman-m (part 1)

* RequestMapper : care about diff

* Code review by @raman-m (part 2)

* Fix Should_return_OK_status_and_multiline_indented_json_response_with_json_options_for_custom_builder

* Update configuration.rst

Add DownstreamVersionPolicy section

* Update docs

* Rename `DownstreamVersionPolicy` to `DownstreamHttpVersionPolicy`

* update docs after prop renaming

* Sort props

---------

Co-authored-by: Guillaume Gnaegi <58469901+ggnaegi@users.noreply.github.com>
Co-authored-by: Raman Maksimchuk <dotnet044@gmail.com>

.circleci/config.yml

@@ -8,13 +8,13 @@ jobs:
     resource_class: medium+
     steps:
       - checkout
-      - run: dotnet tool restore && dotnet cake
+      - run: dotnet dev-certs https && dotnet tool restore && dotnet cake
   release:
     docker:
       - image: ocelot2/circleci-build:latest
     steps:
       - checkout
-      - run: dotnet tool restore && dotnet cake --target=Release
+      - run: dotnet dev-certs https && dotnet tool restore && dotnet cake --target=Release
 workflows:
   version: 2
   main:

docs/features/configuration.rst

@@ -26,6 +26,7 @@ Here is an example Route configuration. You don't need to set all of these thing
     "DownstreamPathTemplate": "/",
     "DownstreamHttpMethod": "",
     "DownstreamHttpVersion": "",
+    "DownstreamHttpVersionPolicy": "",
     "AddHeadersToRequest": {},
     "AddClaimsToRequest": {},
     "RouteClaimsRequirement": {},
@@ -404,11 +405,76 @@ Registering a callback
         }
     }
 
+.. _config-http-version:
+
 DownstreamHttpVersion
 ---------------------
 
 Ocelot allows you to choose the HTTP version it will use to make the proxy request. It can be set as ``1.0``, ``1.1`` or ``2.0``.
 
+* `HttpVersion Class <https://learn.microsoft.com/en-us/dotnet/api/system.net.httpversion>`_
+
+.. _config-version-policy:
+
+DownstreamHttpVersionPolicy [#f5]_
+----------------------------------
+
+This routing property enables the configuration of the ``VersionPolicy`` property within ``HttpRequestMessage`` objects for downstream HTTP requests.
+For additional details, refer to the following documentation:
+
+* `HttpRequestMessage.VersionPolicy Property <https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httprequestmessage.versionpolicy>`_
+* `HttpVersionPolicy Enum <https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpversionpolicy>`_
+* `HttpVersion Class <https://learn.microsoft.com/en-us/dotnet/api/system.net.httpversion>`_
+
+The ``DownstreamHttpVersionPolicy`` option is intricately linked with the :ref:`config-http-version` setting.
+Therefore, merely specifying ``DownstreamHttpVersion`` may sometimes be inadequate, particularly if your downstream services or Ocelot logs report HTTP connection errors such as ``PROTOCOL_ERROR``.
+In these routes, selecting the precise ``DownstreamHttpVersionPolicy`` value is crucial for the ``HttpVersion`` policy to prevent such protocol errors.
+
+HTTP/2 version policy
+^^^^^^^^^^^^^^^^^^^^^
+
+**Given** you aim to ensure a smooth HTTP/2 connection setup for the Ocelot app and downstream services with SSL enabled:
+
+.. code-block:: json
+
+  {
+    "DownstreamScheme": "https",
+    "DownstreamHttpVersion": "2.0",
+    "DownstreamHttpVersionPolicy": "", // empty
+    "DangerousAcceptAnyServerCertificateValidator": true
+  }
+
+**And** you configure global settings to use Kestrel with this snippet:
+
+.. code-block:: csharp
+
+    var builder = WebApplication.CreateBuilder(args);
+    builder.WebHost.ConfigureKestrel(serverOptions =>
+    {
+        serverOptions.ConfigureEndpointDefaults(listenOptions =>
+        {
+            listenOptions.Protocols = HttpProtocols.Http2;
+        });
+    });
+
+**When** all components are set to communicate exclusively via HTTP/2 without TLS (plain HTTP).
+
+**Then** the downstream services may display error messages such as:
+
+.. code-block::
+
+  HTTP/2 connection error (PROTOCOL_ERROR): Invalid HTTP/2 connection preface
+
+To resolve the issue, ensure that ``HttpRequestMessage`` has its ``VersionPolicy`` set to ``RequestVersionOrHigher``.
+Therefore, the ``DownstreamHttpVersionPolicy`` should be defined as follows:
+
+.. code-block:: json
+
+  {
+    "DownstreamHttpVersion": "2.0",
+    "DownstreamHttpVersionPolicy": "RequestVersionOrHigher" // !
+  }
+
 Dependency Injection
 --------------------
 
@@ -434,8 +500,10 @@ You can find additional details in the dedicated :ref:`di-configuration-overview
 .. [#f2] ":ref:`config-merging-tomemory`" subfeature is based on the ``MergeOcelotJson`` enumeration type with values: ``ToFile`` and ``ToMemory``. The 1st one is implicit by default, and the second one is exactly what you need when merging to memory. See more details on implementations in the `ConfigurationBuilderExtensions`_ class.
 .. [#f3] :ref:`di-the-addocelot-method` adds default ASP.NET services to DI container. You could call another extended :ref:`di-addocelotusingbuilder-method` while configuring services to develop your own :ref:`di-custom-builder`. See more instructions in the ":ref:`di-addocelotusingbuilder-method`" section of :doc:`../features/dependencyinjection` feature.
 .. [#f4] ":ref:`config-consul-key`" feature was requested in `issue 346 <https://github.com/ThreeMammals/Ocelot/issues/346>`_ as a part of version `7.0.0 <https://github.com/ThreeMammals/Ocelot/releases/tag/7.0.0>`_.
+.. [#f5] ":ref:`config-version-policy`" feature was requested in `issue 1672 <https://github.com/ThreeMammals/Ocelot/issues/1672>`_ as a part of version `24.0`_.
 
 .. _20.0: https://github.com/ThreeMammals/Ocelot/releases/tag/20.0.0
 .. _23.2: https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0
+.. _24.0: https://github.com/ThreeMammals/Ocelot/releases/tag/24.0.0
 .. _ocelot.json: https://github.com/ThreeMammals/Ocelot/blob/main/test/Ocelot.ManualTest/ocelot.json
 .. _ConfigurationBuilderExtensions: https://github.com/ThreeMammals/Ocelot/blob/develop/src/Ocelot/DependencyInjection/ConfigurationBuilderExtensions.cs

src/Ocelot/Configuration/Builder/DownstreamRouteBuilder.cs

@@ -40,6 +40,7 @@ public class DownstreamRouteBuilder
     private SecurityOptions _securityOptions;
     private string _downstreamHttpMethod;
     private Version _downstreamHttpVersion;
+    private HttpVersionPolicy _downstreamHttpVersionPolicy;
     private Dictionary<string, UpstreamHeaderTemplate> _upstreamHeaders;
 
     public DownstreamRouteBuilder()
@@ -268,6 +269,12 @@ public DownstreamRouteBuilder WithUpstreamHeaders(Dictionary<string, UpstreamHea
         return this;
     }
 
+    public DownstreamRouteBuilder WithDownstreamHttpVersionPolicy(HttpVersionPolicy downstreamHttpVersionPolicy)
+    {
+        _downstreamHttpVersionPolicy = downstreamHttpVersionPolicy;
+        return this;
+    }
+
     public DownstreamRoute Build()
     {
         return new DownstreamRoute(
@@ -305,6 +312,7 @@ public DownstreamRoute Build()
             _securityOptions,
             _downstreamHttpMethod,
             _downstreamHttpVersion,
+            _downstreamHttpVersionPolicy,
             _upstreamHeaders);
     }
 }

src/Ocelot/Configuration/Builder/RouteBuilder.cs

@@ -76,8 +76,7 @@ public Route Build()
                 _upstreamTemplatePattern,
                 _upstreamHost,
                 _aggregator,
-                _upstreamHeaders
-                );
+                _upstreamHeaders);
         }
     }
 }

src/Ocelot/Configuration/Creator/ConfigurationCreator.cs

@@ -12,14 +12,16 @@ public class ConfigurationCreator : IConfigurationCreator
         private readonly IAdministrationPath _adminPath;
         private readonly ILoadBalancerOptionsCreator _loadBalancerOptionsCreator;
         private readonly IVersionCreator _versionCreator;
+        private readonly IVersionPolicyCreator _versionPolicyCreator;
 
         public ConfigurationCreator(
             IServiceProviderConfigurationCreator serviceProviderConfigCreator,
             IQoSOptionsCreator qosOptionsCreator,
             IHttpHandlerOptionsCreator httpHandlerOptionsCreator,
             IServiceProvider serviceProvider,
             ILoadBalancerOptionsCreator loadBalancerOptionsCreator,
-            IVersionCreator versionCreator
+            IVersionCreator versionCreator,
+            IVersionPolicyCreator versionPolicyCreator
             )
         {
             _adminPath = serviceProvider.GetService<IAdministrationPath>();
@@ -28,6 +30,7 @@ IVersionCreator versionCreator
             _qosOptionsCreator = qosOptionsCreator;
             _httpHandlerOptionsCreator = httpHandlerOptionsCreator;
             _versionCreator = versionCreator;
+            _versionPolicyCreator = versionPolicyCreator;
         }
 
         public InternalConfiguration Create(FileConfiguration fileConfiguration, List<Route> routes)
@@ -43,6 +46,8 @@ public InternalConfiguration Create(FileConfiguration fileConfiguration, List<Ro
             var adminPath = _adminPath?.Path;
 
             var version = _versionCreator.Create(fileConfiguration.GlobalConfiguration.DownstreamHttpVersion);
+
+            var versionPolicy = _versionPolicyCreator.Create(fileConfiguration.GlobalConfiguration.DownstreamHttpVersionPolicy);
 
             return new InternalConfiguration(routes,
                 adminPath,
@@ -52,7 +57,8 @@ public InternalConfiguration Create(FileConfiguration fileConfiguration, List<Ro
                 fileConfiguration.GlobalConfiguration.DownstreamScheme,
                 qosOptions,
                 httpHandlerOptions,
-                version
+                version,
+                versionPolicy
                 );
         }
     }

src/Ocelot/Configuration/Creator/DynamicsCreator.cs

@@ -7,11 +7,13 @@ public class DynamicsCreator : IDynamicsCreator
     {
         private readonly IRateLimitOptionsCreator _rateLimitOptionsCreator;
         private readonly IVersionCreator _versionCreator;
+        private readonly IVersionPolicyCreator _versionPolicyCreator;
 
-        public DynamicsCreator(IRateLimitOptionsCreator rateLimitOptionsCreator, IVersionCreator versionCreator)
+        public DynamicsCreator(IRateLimitOptionsCreator rateLimitOptionsCreator, IVersionCreator versionCreator, IVersionPolicyCreator versionPolicyCreator)
         {
             _rateLimitOptionsCreator = rateLimitOptionsCreator;
             _versionCreator = versionCreator;
+            _versionPolicyCreator = versionPolicyCreator;
         }
 
         public List<Route> Create(FileConfiguration fileConfiguration)
@@ -27,12 +29,14 @@ private Route SetUpDynamicRoute(FileDynamicRoute fileDynamicRoute, FileGlobalCon
                 .Create(fileDynamicRoute.RateLimitRule, globalConfiguration);
 
             var version = _versionCreator.Create(fileDynamicRoute.DownstreamHttpVersion);
+            var versionPolicy = _versionPolicyCreator.Create(fileDynamicRoute.DownstreamHttpVersionPolicy);
 
             var downstreamRoute = new DownstreamRouteBuilder()
                 .WithEnableRateLimiting(rateLimitOption.EnableRateLimiting)
                 .WithRateLimitOptions(rateLimitOption)
                 .WithServiceName(fileDynamicRoute.ServiceName)
                 .WithDownstreamHttpVersion(version)
+                .WithDownstreamHttpVersionPolicy(versionPolicy)
                 .Build();
 
             var route = new RouteBuilder()

src/Ocelot/Configuration/Creator/HttpVersionPolicyCreator.cs

@@ -0,0 +1,20 @@
+namespace Ocelot.Configuration.Creator;
+
+/// <summary>
+/// Default implementation of the <see cref="IVersionPolicyCreator"/> interface.
+/// </summary>
+public class HttpVersionPolicyCreator : IVersionPolicyCreator
+{
+    /// <summary>
+    /// Creates a <see cref="HttpVersionPolicy"/> by a string.
+    /// </summary>
+    /// <param name="downstreamHttpVersionPolicy">The string representation of the version policy.</param>
+    /// <returns>An <see cref="HttpVersionPolicy"/> enumeration value.</returns>
+    public HttpVersionPolicy Create(string downstreamHttpVersionPolicy) => downstreamHttpVersionPolicy switch
+    {
+        VersionPolicies.RequestVersionExact => HttpVersionPolicy.RequestVersionExact,
+        VersionPolicies.RequestVersionOrHigher => HttpVersionPolicy.RequestVersionOrHigher,
+        VersionPolicies.RequestVersionOrLower => HttpVersionPolicy.RequestVersionOrLower,
+        _ => HttpVersionPolicy.RequestVersionOrLower,
+    };
+}

src/Ocelot/Configuration/Creator/IVersionPolicyCreator.cs

@@ -0,0 +1,14 @@
+namespace Ocelot.Configuration.Creator;
+
+/// <summary>
+/// Defines conversions from version policy strings to <see cref="HttpVersionPolicy"/> enumeration values.
+/// </summary>
+public interface IVersionPolicyCreator
+{
+    /// <summary>
+    /// Creates a <see cref="HttpVersionPolicy"/> by a string.
+    /// </summary>
+    /// <param name="downstreamHttpVersionPolicy">The string representation of the version policy.</param>
+    /// <returns>An <see cref="HttpVersionPolicy"/> enumeration value.</returns>
+    HttpVersionPolicy Create(string downstreamHttpVersionPolicy);
+}

src/Ocelot/Configuration/Creator/RoutesCreator.cs

@@ -1,6 +1,6 @@
 using Ocelot.Configuration.Builder;
 using Ocelot.Configuration.File;
-
+
 namespace Ocelot.Configuration.Creator
 {
     public class RoutesCreator : IRoutesCreator
@@ -21,6 +21,7 @@ public class RoutesCreator : IRoutesCreator
         private readonly IRouteKeyCreator _routeKeyCreator;
         private readonly ISecurityOptionsCreator _securityOptionsCreator;
         private readonly IVersionCreator _versionCreator;
+        private readonly IVersionPolicyCreator _versionPolicyCreator;
 
         public RoutesCreator(
             IClaimsToThingCreator claimsToThingCreator,
@@ -38,6 +39,7 @@ public RoutesCreator(
             IRouteKeyCreator routeKeyCreator,
             ISecurityOptionsCreator securityOptionsCreator,
             IVersionCreator versionCreator,
+            IVersionPolicyCreator versionPolicyCreator,
             IUpstreamHeaderTemplatePatternCreator upstreamHeaderTemplatePatternCreator)
         {
             _routeKeyCreator = routeKeyCreator;
@@ -56,6 +58,7 @@ public RoutesCreator(
             _loadBalancerOptionsCreator = loadBalancerOptionsCreator;
             _securityOptionsCreator = securityOptionsCreator;
             _versionCreator = versionCreator;
+            _versionPolicyCreator = versionPolicyCreator;
             _upstreamHeaderTemplatePatternCreator = upstreamHeaderTemplatePatternCreator;
         }
 
@@ -106,6 +109,8 @@ private DownstreamRoute SetUpDownstreamRoute(FileRoute fileRoute, FileGlobalConf
 
             var downstreamHttpVersion = _versionCreator.Create(fileRoute.DownstreamHttpVersion);
 
+            var downstreamHttpVersionPolicy = _versionPolicyCreator.Create(fileRoute.DownstreamHttpVersionPolicy);
+
             var cacheOptions = _cacheOptionsCreator.Create(fileRoute.FileCacheOptions, globalConfiguration, fileRoute.UpstreamPathTemplate, fileRoute.UpstreamHttpMethod);
 
             var route = new DownstreamRouteBuilder()
@@ -143,6 +148,7 @@ private DownstreamRoute SetUpDownstreamRoute(FileRoute fileRoute, FileGlobalConf
                 .WithDangerousAcceptAnyServerCertificateValidator(fileRoute.DangerousAcceptAnyServerCertificateValidator)
                 .WithSecurityOptions(securityOptions)
                 .WithDownstreamHttpVersion(downstreamHttpVersion)
+                .WithDownstreamHttpVersionPolicy(downstreamHttpVersionPolicy)
                 .WithDownStreamHttpMethod(fileRoute.DownstreamHttpMethod)
                 .Build();
 
@@ -151,14 +157,14 @@ private DownstreamRoute SetUpDownstreamRoute(FileRoute fileRoute, FileGlobalConf
 
         private Route SetUpRoute(FileRoute fileRoute, DownstreamRoute downstreamRoutes)
         {
-            var upstreamTemplatePattern = _upstreamTemplatePatternCreator.Create(fileRoute);
+            var upstreamTemplatePattern = _upstreamTemplatePatternCreator.Create(fileRoute);
             var upstreamHeaderTemplates = _upstreamHeaderTemplatePatternCreator.Create(fileRoute);
 
             var route = new RouteBuilder()
                 .WithUpstreamHttpMethod(fileRoute.UpstreamHttpMethod)
                 .WithUpstreamPathTemplate(upstreamTemplatePattern)
                 .WithDownstreamRoute(downstreamRoutes)
-                .WithUpstreamHost(fileRoute.UpstreamHost)
+                .WithUpstreamHost(fileRoute.UpstreamHost)
                 .WithUpstreamHeaders(upstreamHeaderTemplates)
                 .Build();
 

src/Ocelot/Configuration/Creator/VersionPolicies.cs

@@ -0,0 +1,11 @@
+namespace Ocelot.Configuration.Creator;
+
+/// <summary>
+/// Constants for conversions in concrete classes for the <see cref="IVersionPolicyCreator"/> interface.
+/// </summary>
+public class VersionPolicies
+{
+    public const string RequestVersionExact = nameof(RequestVersionExact);
+    public const string RequestVersionOrLower = nameof(RequestVersionOrLower);
+    public const string RequestVersionOrHigher = nameof(RequestVersionOrHigher);
+}

src/Ocelot/Configuration/DownstreamRoute.cs

@@ -40,6 +40,7 @@ public DownstreamRoute(
             SecurityOptions securityOptions,
             string downstreamHttpMethod,
             Version downstreamHttpVersion,
+            HttpVersionPolicy downstreamHttpVersionPolicy,
             Dictionary<string, UpstreamHeaderTemplate> upstreamHeaders)
         {
             DangerousAcceptAnyServerCertificateValidator = dangerousAcceptAnyServerCertificateValidator;
@@ -75,7 +76,8 @@ public DownstreamRoute(
             AddHeadersToUpstream = addHeadersToUpstream;
             SecurityOptions = securityOptions;
             DownstreamHttpMethod = downstreamHttpMethod;
-            DownstreamHttpVersion = downstreamHttpVersion;
+            DownstreamHttpVersion = downstreamHttpVersion;
+            DownstreamHttpVersionPolicy = downstreamHttpVersionPolicy;
             UpstreamHeaders = upstreamHeaders ?? new();
         }
 
@@ -112,7 +114,19 @@ public DownstreamRoute(
         public bool DangerousAcceptAnyServerCertificateValidator { get; }
         public SecurityOptions SecurityOptions { get; }
         public string DownstreamHttpMethod { get; }
-        public Version DownstreamHttpVersion { get; }
+        public Version DownstreamHttpVersion { get; }
+
+        /// <summary>The <see cref="HttpVersionPolicy"/> enum specifies behaviors for selecting and negotiating the HTTP version for a request.</summary>
+        /// <value>An <see cref="HttpVersionPolicy"/> enum value being mapped from a <see cref="VersionPolicies"/> constant.</value>
+        /// <remarks>
+        /// Related to the <see cref="DownstreamHttpVersion"/> property.
+        /// <list type="bullet">
+        ///   <item><see href="https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpversionpolicy">HttpVersionPolicy Enum</see></item>
+        ///   <item><see href="https://learn.microsoft.com/en-us/dotnet/api/system.net.httpversion">HttpVersion Class</see></item>
+        ///   <item><see href="https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httprequestmessage.versionpolicy">HttpRequestMessage.VersionPolicy Property</see></item>
+        /// </list>
+        /// </remarks>
+        public HttpVersionPolicy DownstreamHttpVersionPolicy { get; }
         public Dictionary<string, UpstreamHeaderTemplate> UpstreamHeaders { get; }
     }
 }