Merge branch 'release/24.0' into feature/1658---Global-UpstreamHeaderTransform-settings-in-GlobalConfiguration-section

Author: raman-m

ReleaseNotes.md

@@ -1,63 +1,39 @@
-## 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)**
+## January 2024 (version {0}) aka [Hornussen](https://www.myswitzerland.com/en-ch/planning/about-switzerland/custom-and-tradition/hornussen-where-the-nouss-flies-from-the-ramp-and-into-the-playing-field/) release
+> Codenamed as **[Hornussen Sport](https://www.youtube.com/results?search_query=Hornussen)**
+> Read the Docs: [Ocelot 23.1](https://ocelot.readthedocs.io/en/23.1.0/)
 
 ### Focus On
 
 <details>
-  <summary><b>System performance</b>. System core performance review, redesign of system core related to routing and content streaming</summary>
-
-  - 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...
+  <summary><b>Multiplexing middleware</b> aka <a href="https://ocelot.readthedocs.io/en/latest/features/requestaggregation.html">Request Aggregation</a> feature</summary>
+ 
+- Significant refactoring and design review of the [Multiplexer](https://github.com/ThreeMammals/Ocelot/tree/develop/src/Ocelot/Multiplexer)
+- Optimizing multiplexer performance: `HttpContext` is not copied when there is only one downstream route, and etc.
+- Fixed [the bug](https://github.com/ThreeMammals/Ocelot/pull/1462) in the multiplexer: `HttpContext.User` information was not copied if there was more than one downstream request.
 </details>
 
 <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.
+  <summary><b>System routing</b>. Content streaming when <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding">Transfer-Encoding</a>: 'chunked'</summary>
 
-  - [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.
+  - Correction of [the bug](https://github.com/ThreeMammals/Ocelot/pull/1972) when creating requests: The header [Transfer-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding): `chunked` was present even when there was no content or the request body size was 0. These cases are now addressed.
 </details>
 
 <details>
-  <summary><b>Middlewares</b>. Total 8 Ocelot middlewares were updated</summary>
+  <summary><b>Updates of the features</b>: QoS, Load Balancer and Error Status Codes</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
+- [Quality of Service](https://ocelot.readthedocs.io/en/latest/features/qualityofservice.html): Possibility of implementation of custom Polly v8.2 providers. New `AddPolly` extension methods.
+- [Load Balancer](https://ocelot.readthedocs.io/en/latest/features/loadbalancer.html): Extension of the route key format, ensuring that the key remains unique for cases of **UpstreamHost** route property and **ServiceName** vs **ServiceNamespace** properties in Consul setup.
+- [Error Status Codes](https://ocelot.readthedocs.io/en/latest/features/errorcodes.html): When [413 Content Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413), Ocelot now returns a 413 `PayloadTooLargeError` (Ocelot error code `41`).
 </details>
 
 <details>
-  <summary>Documentation for <b>Authentication</b>, <b>Caching</b>, <b>Kubernetes</b> and <b>Routing</b></summary>
+  <summary>Documentation for <b>Request Aggregation</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)
+  - [Request Aggregation](https://ocelot.readthedocs.io/en/latest/features/requestaggregation.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
+  - See [all bugs](https://github.com/ThreeMammals/Ocelot/issues?q=is%3Aissue+is%3Aclosed+label%3Abug+milestone%3AJanuary%2724) of the [January'24](https://github.com/ThreeMammals/Ocelot/milestone/4) milestone
 </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

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

docs/features/requestaggregation.rst

@@ -1,22 +1,21 @@
-Request Aggregation
-===================
+Request Aggregation [#f1]_
+==========================
 
 Ocelot allows you to specify Aggregate Routes that compose multiple normal Routes and map their responses into one object.
 This is usually where you have a client that is making multiple requests to a server where it could just be one.
-This feature allows you to start implementing back-end for a front-end (BFF) type architecture with Ocelot.
-
-This feature was requested as part of `issue 79 <https://github.com/ThreeMammals/Ocelot/issues/79>`_ and further improvements were made as part of `issue 298 <https://github.com/ThreeMammals/Ocelot/issues/298>`_.
+This feature allows you to start implementing back-end for a front-end (BFF) type architecture with Ocelot. [#f1]_
 
 In order to set this up you must do something like the following in your **ocelot.json**.
 Here we have specified two normal Routes and each one has a **Key** property. 
 We then specify an Aggregate that composes the two Routes using their keys in the **RouteKeys** list and says then we have the **UpstreamPathTemplate** which works like a normal Route.
 Obviously you cannot have duplicate **UpstreamPathTemplates** between **Routes** and **Aggregates**.
-You can use all of Ocelot's normal Route options apart from **RequestIdKey** (explained in `gotchas <#gotchas>`_ below).
+You can use all of Ocelot's normal Route options apart from **RequestIdKey** (explained in :ref:`agg-gotchas` below).
 
 Basic Expecting JSON from Downstream Services
 ---------------------------------------------
 
 .. code-block:: json
+
   {
     "Routes": [
       {
@@ -43,10 +42,7 @@ Basic Expecting JSON from Downstream Services
     "Aggregates": [
       {
         "UpstreamPathTemplate": "/",
-        "RouteKeys": [
-          "Tom",
-          "Laura"
-        ]
+        "RouteKeys": [ "Tom", "Laura" ]
       }
     ]
   }
@@ -81,16 +77,23 @@ Here, you could use aggregation to get 1) all the comments, 2) attach the author
 
 In concrete terms:
 
-1) "/Comments" -> contains the authorId property
-2) "/users/{userId}" with {userId} replaced by authorId to obtain the user's details.
+1) ``/Comments`` contains the authorId property
+2) ``/users/{userId}`` with ``{userId}`` replaced by **authorId** to obtain the user's details.
+
+This functionality is still in its early stages, but it does allow you to search for data based on an initial request.
 
-This functionality is still in its early stages, but it does allow you to search for data based on an initial request. To perform the mapping, you need to use **AggregateRouteConfig**.
+To perform the mapping, you need to use **AggregateRouteConfig**:
 
 .. code-block:: csharp
 
-    new AggregateRouteConfig{ RouteKey = "UserDetails", JsonPath = "$[*].authorId", Parameter = "userId" };
+    new AggregateRouteConfig
+    {
+        RouteKey = "UserDetails",
+        JsonPath = "$[*].authorId",
+        Parameter = "userId"
+    };
 
-**RouteKey** is used as a reference for the route, **JsonPath** indicates where the parameter you are interested in is located in the first request response body and **Parameter** tells us that the value for authorId should be used for the request parameter userId.
+**RouteKey** is used as a reference for the route, **JsonPath** indicates where the parameter you are interested in is located in the first request response body and **Parameter** tells us that the value for ``authorId`` should be used for the request parameter ``userId``.
 
 Register Your Own Aggregators
 -----------------------------
@@ -138,7 +141,7 @@ The **ocelot.json** setup is pretty much the same as the basic aggregation appro
 
 Here we have added an aggregator called ``FakeDefinedAggregator``. Ocelot is going to look for this aggregator when it tries to aggregate this Route.
 
-In order to make the aggregator available we must add the ``FakeDefinedAggregator`` to the ``OcelotBuilder`` being returned by ``AddOcelot()`` [#f1]_ like below:
+In order to make the aggregator available we must add the ``FakeDefinedAggregator`` to the ``OcelotBuilder`` being returned by ``AddOcelot()`` [#f2]_ like below:
 
 .. code-block:: csharp
 
@@ -209,6 +212,8 @@ Below is an example of an aggregator that you could implement for your solution:
       }
   }
 
+.. _agg-gotchas:
+
 Gotchas
 -------
 
@@ -218,4 +223,5 @@ Aggregation only supports the ``GET`` HTTP verb.
 
 """"
 
-.. [#f1] The ``AddOcelot`` method adds default ASP.NET services to DI-container. You could call another more extended ``AddOcelotUsingBuilder`` method while configuring services to build and use custom builder via an ``IMvcCoreBuilder`` interface object. See more instructions in :doc:`../features/dependencyinjection`, "**The AddOcelotUsingBuilder method**" section.
+.. [#f1] This feature was requested as part of `issue 79 <https://github.com/ThreeMammals/Ocelot/issues/79>`_ and further improvements were made as part of `issue 298 <https://github.com/ThreeMammals/Ocelot/issues/298>`_. A significant refactoring and revision of the `Multiplexer <https://github.com/ThreeMammals/Ocelot/tree/develop/src/Ocelot/Multiplexer>`_ design was carried out on March 4, 2024 in version `23.1 <https://github.com/ThreeMammals/Ocelot/releases/tag/23.1.0>`_, see PRs `1826 <https://github.com/ThreeMammals/Ocelot/pull/1826>`_ and `1462 <https://github.com/ThreeMammals/Ocelot/pull/1462>`_.
+.. [#f2] The ``AddOcelot`` method adds default ASP.NET services to DI-container. You could call another more extended ``AddOcelotUsingBuilder`` method while configuring services to build and use custom builder via an ``IMvcCoreBuilder`` interface object. See more instructions in :doc:`../features/dependencyinjection`, "**The AddOcelotUsingBuilder method**" section.

docs/index.rst

@@ -1,4 +1,4 @@
-Welcome to Ocelot `23.0 <https://github.com/ThreeMammals/Ocelot/releases/tag/23.0.0>`_
+Welcome to Ocelot `23.1 <https://github.com/ThreeMammals/Ocelot/releases/tag/23.1.0>`_
 ======================================================================================
 
 Thanks for taking a look at the Ocelot documentation! Please use the left hand navigation to get around.