Release 23.0 | Artifacts | +semver: breaking (ThreeMammals#1962)

* Review & update docs and fix build warnings

* Update ReleaseNotes.md: Draft template for build script

* Final version of Release Notes

Author: raman-m

ReleaseNotes.md

@@ -1,20 +1,63 @@
-## Hotfix release (version {0})
-> Default timeout vs the [Quality of Service](https://ocelot.readthedocs.io/en/latest/features/qualityofservice.html) feature
+## November-December 2023 (version {0}) aka [Sunny Koliada](https://www.google.com/search?q=winter+solstice) release
+> Codenamed as **[Sunny Koliada](https://www.bing.com/search?q=winter+solstice)**
 
-Special thanks to **Alvin Huang**, @huanguolin!
+### Focus On
 
-### About
-The bug is related to the **Quality of Service** feature (aka **QoS**) and the [HttpClient.Timeout](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient.timeout) property.
-- If JSON `QoSOptions` section is defined in the route config, then the bug is masked rather than active, and the timeout value is assigned from the [QoS TimeoutValue](https://ocelot.readthedocs.io/en/latest/features/qualityofservice.html#quality-of-service:~:text=%22TimeoutValue%22%3A%205000) property.
-- If the `QoSOptions` section **is not** defined in the route config or the [TimeoutValue](https://ocelot.readthedocs.io/en/latest/features/qualityofservice.html#quality-of-service:~:text=%22TimeoutValue%22%3A%205000) property is missing, then the bug is **active** and affects downstream requests that **never time out**.
+<details>
+  <summary><b>System performance</b>. System core performance review, redesign of system core related to routing and content streaming</summary>
 
-### Technical info
-In version [22.0](https://github.com/ThreeMammals/Ocelot/releases/tag/22.0.0), the bug was found in the explicit default constructor of the [FileQoSOptions](https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Configuration/File/FileQoSOptions.cs) class with a maximum [TimeoutValue](https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Configuration/File/FileQoSOptions.cs#L9). Previously, the default constructor was implicit with the default assignment of zero `0` to all `int` properties.
+  - Modification of the `RequestMapper` with a brand new `StreamHttpContent` class, in `Ocelot.Request.Mapper` namespace. The request body is no longer copied when it is handled by the API gateway, avoiding Out-of-Memory issues in pods/containers. This significantly reduces the gateway's memory consumption, and allows you to transfer content larger than 2 GB in streaming scenarios.
+  - Introduction of a new Message Invoker pool, in `Ocelot.Requester` namespace. We have replaced the [HttpClient](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient) class with [HttpMessageInvoker](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpmessageinvoker), which is the base class for `HttpClient`. The overall logic for managing the pool has been simplified, resulting in a reduction in the number of CPU cycles.
+  - Full HTTP content buffering is deactivated, resulting in a 50% reduction in memory consumption and a performance improvement of around 10%. Content is no longer copied on the API gateway, avoiding Out-of-Memory issues.
+  - **TODO** Include screenshots from Production...
+</details>
 
-The new explicit default constructor breaks the old implementation of [QoS TimeoutValue](https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Requester/HttpClientBuilder.cs#L53-L55) logic, as our [QoS documentation](https://ocelot.readthedocs.io/en/latest/features/qualityofservice.html#quality-of-service:~:text=If%20you%20do%20not%20add%20a%20QoS%20section%2C%20QoS%20will%20not%20be%20used%2C%20however%20Ocelot%20will%20default%20to%20a%2090%20seconds%20timeout%20on%20all%20downstream%20requests.) states:
-![image](https://github.com/ThreeMammals/Ocelot/assets/12430413/2c6b2cd3-e1c6-4510-9e46-883468c140ec) <br/>
-**Finally**, the "default 90 second" logic for `HttpClient` breaks down when there are no **QoS** options and all requests on those routes are infinite, if, for example, downstream services are down or stuck.
+<details>
+  <summary><b>Ocelot extra packages</b>. Total 3 Ocelot packs were updated</summary>
+ 
+  - [Ocelot.Cache.CacheManager](https://github.com/ThreeMammals/Ocelot/tree/main/src/Ocelot.Cache.CacheManager): Introduced default cache key generator with improved performance (the `DefaultCacheKeyGenerator` class). Old version of `CacheKeyGenerator` had significant performance issue when reading full content of HTTP request for caching key calculation of MD5 hash value. This hash value was excluded from the caching key.
+  - [Ocelot.Provider.Kubernetes](https://github.com/ThreeMammals/Ocelot/tree/main/src/Ocelot.Provider.Kubernetes): Fixed long lasting breaking change being added in version [15.0.0](https://github.com/ThreeMammals/Ocelot/releases/tag/15.0.0), see commit https://github.com/ThreeMammals/Ocelot/commit/6e5471a714dddb0a3a40fbb97eac2810cee1c78d. The bug persisted for more than 3 years in versions **15.0.0-22.0.1**, being masked multiple times via class renaming! **Special Thanks to @ZisisTsatsas** who once again brought this issue to our attention, and our team finally realized that we had a breaking change and the provider was broken.
 
-#### The Bug Artifacts
-- Reported bug issue: [1833](https://github.com/ThreeMammals/Ocelot/issues/1833) by @huanguolin
-- Hotfix PR: [1834](https://github.com/ThreeMammals/Ocelot/pull/1834) by @huanguolin
+  - [Ocelot.Provider.Polly](https://github.com/ThreeMammals/Ocelot/tree/main/src/Ocelot.Provider.Polly): A minor changes without feature delivery. We are preparing for a major update to the package in the next release.
+</details>
+
+<details>
+  <summary><b>Middlewares</b>. Total 8 Ocelot middlewares were updated</summary>
+ 
+  - `AuthenticationMiddleware`: Added new [Multiple Authentication Schemes](https://github.com/ThreeMammals/Ocelot/pull/1870) feature by @MayorSheFF 
+  - `OutputCacheMiddleware`, `RequestIdMiddleware`: Added new [Cache by Header Value](https://github.com/ThreeMammals/Ocelot/pull/1172) by @EngRajabi, and redesigned as [Default CacheKeyGenerator](https://github.com/ThreeMammals/Ocelot/pull/1849) feature by @raman-m
+  - `DownstreamUrlCreatorMiddleware`: Fixed [bug](https://github.com/ThreeMammals/Ocelot/issues/748) for ending/omitting slash in path templates aka [Empty placeholders](https://github.com/ThreeMammals/Ocelot/pull/1911) feature by @AlyHKafoury 
+  - `ConfigurationMiddleware`, `HttpRequesterMiddleware`, `ResponderMiddleware`: System upgrade for [Custom HttpMessageInvoker pooling](https://github.com/ThreeMammals/Ocelot/pull/1824) feature by @ggnaegi
+  - `DownstreamRequestInitialiserMiddleware`: System upgrade for [Performance of Request Mapper](https://github.com/ThreeMammals/Ocelot/pull/1724) feature by @ggnaegi
+</details>
+
+<details>
+  <summary>Documentation for <b>Authentication</b>, <b>Caching</b>, <b>Kubernetes</b> and <b>Routing</b></summary>
+ 
+  - [Authentication](https://ocelot.readthedocs.io/en/latest/features/authentication.html)
+  - [Caching](https://ocelot.readthedocs.io/en/latest/features/caching.html)
+  - [Kubernetes](https://ocelot.readthedocs.io/en/latest/features/kubernetes.html)
+  - [Routing](https://ocelot.readthedocs.io/en/latest/features/routing.html)
+</details>
+
+<details>
+  <summary><b>Stabilization</b> aka bug fixing</summary>
+
+  - See [all bugs](https://github.com/ThreeMammals/Ocelot/issues?q=is%3Aissue+milestone%3ANov-December%2723+is%3Aclosed+label%3Abug) of the [Nov-December'23](https://github.com/ThreeMammals/Ocelot/milestone/2) milestone
+</details>
+
+<details>
+  <summary><b>Testing</b></summary>
+
+  - The `Ocelot.Benchmarks` testing project has been updated with new `PayloadBenchmarks` and `ResponseBenchmarks` by @ggnaegi
+  - The `Ocelot.AcceptanceTests` testing project has been refactored by @raman-m using the new `AuthenticationSteps` class, and more refactoring will be done in future releases
+</details>
+
+### Roadmap
+We would like to share our team's plans for the future regarding: development trends, ideas, community expectations, etc.
+- **Code Review and Performance Improvements**. Without a doubt, we care about code quality every day, following best development practices. And we review, test, refactor, and redesign features with overall performance in mind. In the next few releases (versions 23.x-24.0) we will take care of: generic providers, multiplexing middleware (Aggregation feature), memory management.
+- **Server-Sent Events protocol support**. There is a lot of community interest in this HTTP-based protocol.
+- **Long Polling for Consul provider**. [Consul](https://www.consul.io/) is our leading technology for service discovery. We are constantly improving the use cases for the `Ocelot.Provider.Consul` package and trying to improve the code inside the package.
+- **QoS feature refactoring**. [Polly](https://github.com/App-vNext/Polly/) was released with the new v.8.2+ after .NET 8. So we have to update `Ocelot.Provider.Polly` package taking into account new Polly behavior of redesigned features.
+- **Brainstorming** to redesign Rate Limiting, Websockets. More details in future release notes.
+- **Planning** of support for Swagger and gRPC proto. More details in future release notes.

docs/conf.py

@@ -7,9 +7,9 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'Ocelot'
-copyright = ' 2023 ThreeMammals Ocelot team'
+copyright = ' 2016-2024 ThreeMammals Ocelot team'
 author = 'Tom Pallister, Ocelot Core team at ThreeMammals'
-release = '22.0'
+release = '23.0'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/features/authentication.rst

@@ -21,13 +21,13 @@ users must register authentication services in their **Startup.cs** as usual but
 In this example ``MyKey`` is `the scheme <https://learn.microsoft.com/en-us/aspnet/core/security/authentication/#authentication-scheme>`_ that this provider has been registered with.
 We then map this to a Route in the configuration using the following `AuthenticationOptions <https://github.com/search?q=repo%3AThreeMammals%2FOcelot%20AuthenticationOptions&type=code>`_ properties:
 
-* ``AuthenticationProviderKey`` is a string object, obsolete. [#f1]_ This is legacy definition when you define :ref:`authentication-single` (scheme).
+* ``AuthenticationProviderKey`` is a string object, obsolete [#f1]_. This is legacy definition when you define :ref:`authentication-single`.
 * ``AuthenticationProviderKeys`` is an array of strings, the recommended definition of :ref:`authentication-multiple` feature.
 
-.. authentication-single:
+.. _authentication-single:
 
-Single Key [#f1]_
------------------
+Single Key aka Authentication Scheme [#f1]_
+-------------------------------------------
 
     | Property: ``AuthenticationOptions.AuthenticationProviderKey``
 
@@ -46,7 +46,7 @@ If there isn't then Ocelot will not start up. If there is then the Route will us
 If a Route is authenticated, Ocelot will invoke whatever scheme is associated with it while executing the authentication middleware.
 If the request fails authentication, Ocelot returns a HTTP status code `401 Unauthorized <https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401>`_.
 
-.. authentication-multiple:
+.. _authentication-multiple:
 
 Multiple Authentication Schemes [#f2]_
 --------------------------------------
@@ -55,7 +55,7 @@ Multiple Authentication Schemes [#f2]_
 
 In real world of ASP.NET, apps may need to support multiple types of authentication by single Ocelot app instance.
 To register `multiple authentication schemes <https://learn.microsoft.com/en-us/aspnet/core/security/authorization/limitingidentitybyscheme#use-multiple-authentication-schemes>`_
-(authentication provider keys) for each appropriate authentication provider, use and develop this abstract configuration of two or more schemes:
+(`authentication provider keys <https://github.com/search?q=repo%3AThreeMammals%2FOcelot%20AuthenticationProviderKey&type=code>`_) for each appropriate authentication provider, use and develop this abstract configuration of two or more schemes:
 
 .. code-block:: csharp
 
@@ -68,8 +68,8 @@ To register `multiple authentication schemes <https://learn.microsoft.com/en-us/
             .AddMyProvider("MyKey", options => { /* Custom auth setup */ });
     }
 
-In this example, the schemes ``MyKey`` and ``Bearer`` represent the keys which these providers have been registered with.
-We then map these schemes to a Route in the configuration, as shown below
+In this example, the ``MyKey`` and ``Bearer`` schemes represent the keys with which these providers were registered.
+We then map these schemes to a Route in the configuration as shown below.
 
 .. code-block:: json
 
@@ -83,9 +83,8 @@ Afterward, Ocelot applies all steps that are specified for ``AuthenticationProvi
 **Note** that the order of the keys in an array definition does matter! We use a "First One Wins" authentication strategy.
 
 Finally, we would say that registering providers, initializing options, forwarding authentication artifacts can be a "real" coding challenge.
-If you're stuck or don't know what to do, just find inspiration in our `acceptance tests <https://github.com/search?q=repo%3AThreeMammals%2FOcelot%20MultipleAuthSchemesFeatureTests&type=code>`_ 
-(currently for `Identity Server 4 <https://identityserver4.readthedocs.io/>`_ only).
-We would appreciate any new PRs to add extra acceptance tests for your custom scenarios with `multiple authentication schemes <https://learn.microsoft.com/en-us/aspnet/core/security/authorization/limitingidentitybyscheme#use-multiple-authentication-schemes>`__. [#f2]_
+If you're stuck or don't know what to do, just find inspiration in our `acceptance tests <https://github.com/search?q=repo%3AThreeMammals%2FOcelot+MultipleAuthSchemesFeatureTests+language%3AC%23&type=code&l=C%23>`_
+(currently for `Identity Server 4 <https://identityserver4.readthedocs.io/>`_ only) [#f3]_.
 
 JWT Tokens
 ----------
@@ -210,5 +209,6 @@ Please, open `Show and tell <https://github.com/ThreeMammals/Ocelot/discussions/
 
 """"
 
-.. [#f1] Use the ``AuthenticationProviderKeys`` property instead of ``AuthenticationProviderKey`` one. We supports this obsolete property because of backward compatibility and allowing migrations. In future releases the property can be removed as a breaking change.
-.. [#f2] `Multiple authentication schemes <https://learn.microsoft.com/en-us/aspnet/core/security/authorization/limitingidentitybyscheme#use-multiple-authentication-schemes>`__ feature was requested in issues `740 <https://github.com/ThreeMammals/Ocelot/issues/740>`_, `1580 <https://github.com/ThreeMammals/Ocelot/issues/1580>`_ and delivered as a part of `23.0 <https://github.com/ThreeMammals/Ocelot/releases/tag/23.0.0>`_ release.
+.. [#f1] Use the ``AuthenticationProviderKeys`` property instead of ``AuthenticationProviderKey`` one. We support this ``[Obsolete]`` property for backward compatibility and migration reasons. In future releases, the property may be removed as a breaking change.
+.. [#f2] "`Multiple authentication schemes <https://learn.microsoft.com/en-us/aspnet/core/security/authorization/limitingidentitybyscheme#use-multiple-authentication-schemes>`__" feature was requested in issues `740 <https://github.com/ThreeMammals/Ocelot/issues/740>`_, `1580 <https://github.com/ThreeMammals/Ocelot/issues/1580>`_ and delivered as a part of `23.0 <https://github.com/ThreeMammals/Ocelot/releases/tag/23.0.0>`_ release.
+.. [#f3] We would appreciate any new PRs to add extra acceptance tests for your custom scenarios with `multiple authentication schemes <https://learn.microsoft.com/en-us/aspnet/core/security/authorization/limitingidentitybyscheme#use-multiple-authentication-schemes>`__.

docs/features/caching.rst

@@ -6,6 +6,9 @@ This is an amazing project that is solving a lot of caching problems. We would r
 
 The following example shows how to add **CacheManager** to Ocelot so that you can do output caching. 
 
+Install
+-------
+
 First of all, add the following `NuGet package <https://www.nuget.org/packages/Ocelot.Cache.CacheManager>`_:
 
 .. code-block:: powershell
@@ -26,11 +29,18 @@ The second thing you need to do something like the following to your ``Configure
             .AddCacheManager(x => x.WithDictionaryHandle());
     });
 
+Configuration
+-------------
+
 Finally, in order to use caching on a route in your Route configuration add this setting:
 
 .. code-block:: json
 
-    "FileCacheOptions": { "TtlSeconds": 15, "Region": "europe-central", "Header": "Authorization" }
+    "FileCacheOptions": {
+      "TtlSeconds": 15,
+      "Region": "europe-central",
+      "Header": "Authorization"
+    }
 
 In this example **TtlSeconds** is set to 15 which means the cache will expire after 15 seconds.
 The **Region** represents a region of caching. 

docs/features/kubernetes.rst

@@ -5,10 +5,7 @@
 |K8s Logo| Kubernetes [#f1]_ aka K8s
 ====================================
 
-    A part of feature: :doc:`../features/servicediscovery`
-
-About [#f2]_
-------------
+    A part of feature: :doc:`../features/servicediscovery` [#f2]_
 
 Ocelot will call the `K8s <https://kubernetes.io/>`_ endpoints API in a given namespace to get all of the endpoints for a pod and then load balance across them.
 Ocelot used to use the services API to send requests to the `K8s <https://kubernetes.io/>`__ service but this was changed in `PR 1134 <https://github.com/ThreeMammals/Ocelot/pull/1134>`_ because the service did not load balance as expected.
@@ -75,10 +72,10 @@ The example here shows a typical configuration:
       }
     }
 
-Service deployment in **Namespace** ``Dev``, **ServiceDiscoveryProvider** type is ``Kube``, you also can set :ref:`kubernetes-pollkube-provider` type.
+Service deployment in **Namespace** ``Dev``, **ServiceDiscoveryProvider** type is ``Kube``, you also can set :ref:`k8s-pollkube-provider` type.
 Note: **Host**, **Port** and **Token** are no longer in use.
 
-.. kubernetes-pollkube-provider:
+.. _k8s-pollkube-provider:
 
 PollKube provider
 ^^^^^^^^^^^^^^^^^