diff --git a/ReleaseNotes.md b/ReleaseNotes.md index 48db3c3bf..b5ab2023a 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -1,31 +1,84 @@ -## Hotfix release (version {0}) for #2031 issue -> Route path template placeholders and their validation rules +## Spring 2024 (version {0}) aka [Twilight Texas](https://www.timeanddate.com/eclipse/map/2024-april-8) release +> Codenamed: **[Twilight Texas](https://www.timeanddate.com/eclipse/map/2024-april-8)** +> Read the Docs: [Ocelot 23.3](https://ocelot.readthedocs.io/en/23.3.0/) -Special thanks to **[Guillaume Gnaegi](https://github.com/ggnaegi)** and [Fabrizio Mancin](https://github.com/Fabman08)! +### What's new? -### About -The bug is related to the [Placeholders](https://ocelot.readthedocs.io/en/latest/features/routing.html#placeholders) feature in [Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html) and [Routing](https://ocelot.readthedocs.io/en/latest/features/routing.html). -The bug was introduced in version [23.2.0](https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0) as a part of PR #1927. +- **[Service Discovery](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/servicediscovery.rst)**: Introducing a new feature for "[Customization of services creation](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/servicediscovery.rst#consul-service-builder-3)" in two primary service discovery providers: [Consul](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/servicediscovery.rst#consul-service-builder-3) and [Kubernetes](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/kubernetes.rst#downstream-scheme-vs-port-names-3), developed by @raman-m. + The customization for both `Consul` and `Kube` providers in service creation is achieved through the overriding of virtual methods in default implementations. The recommendation was to separate the provider's logic and introduce `public virtual` and `protected virtual` methods in concrete classes, enabling: + - The use of `public virtual` methods as dictated by interface definitions. + - The application of `protected virtual` methods to allow developers to customize atomic operations through inheritance from existing concrete classes. + - The injection of new interface objects into the provider's constructor. + - The overriding of the default behavior of classes. -### Breaking Change -The new [validation rules](https://github.com/ThreeMammals/Ocelot/blob/23.2.0/src/Ocelot/Configuration/Validator/FileConfigurationFluentValidator.cs#L45-L50) of the `FileConfigurationFluentValidator` class do not allow the Ocelot app to start when implicit [placeholders](https://ocelot.readthedocs.io/en/latest/features/routing.html#placeholders) are defined in custom implementations, such as middlewares, delegating handlers, and replaced services in the dependency injection (DI) container. -These new rules are capable of validating explicit [placeholders](https://ocelot.readthedocs.io/en/latest/features/routing.html#placeholders) only within the `UpstreamPathTemplate` and `DownstreamPathTemplate` properties. Unfortunately, they cannot oversee implicit placeholders in custom implementations, and they do not validate early during the Ocelot app startup process. + Ultimately, customization relies on the virtual methods within the default implementation classes, providing developers the flexibility to override them as necessary for highly tailored Consul/K8s configurations in their specific environments. + For further details, refer to the respective pull requests for both providers: + - `Kube` → PR #2052 + - `Consul` → PR #2067 -Ensure that you avoid using version [23.2.0](https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0). If you are currently on that version, upgrade to version [{0}](https://github.com/ThreeMammals/Ocelot/releases/tag/{0}) by applying this hotfix patch. +- **[Routing](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/routing.rst)**: Introducing the new "[Routing based on Request Header](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/routing.rst#upstream-headers-3)" feature by @jlukawska. + In addition to routing via `UpstreamPathTemplate`, you can now define an `UpstreamHeaderTemplates` options dictionary. For a route to match, all headers specified in this section are required to be present in the request headers. + For more details, see PR #1312. -### Technical info -With version [23.2.0](https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0), particularly if you have overridden certain service classes or implemented custom logic that manipulates placeholders, you may encounter Ocelot app crashes accompanied by the following errors in the log: -``` -One or more errors occurred. (Unable to start Ocelot, errors are: XXX) -``` -where `XXX` are the following validation error messages: -- `UpstreamPathTemplate 'UUU' doesn't contain the same placeholders in DownstreamPathTemplate 'DDD'` -- `DownstreamPathTemplate 'DDD' doesn't contain the same placeholders in UpstreamPathTemplate 'UUU'` +- **[Configuration](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/configuration.rst)**: Introducing the "[Custom Default Version Policy](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/configuration.rst#downstreamhttpversionpolicy-3)" feature by @ibnuda. + The configurable `HttpRequestMessage.VersionPolicy` helps avoid HTTP protocol connection errors and stabilizes connections to downstream services, especially when you're not developing those services, documentation is scarce, or the deployed HTTP protocol version is uncertain. + For developers of downstream services, it's possible to `ConfigureKestrel` server and its endpoints with new protocol settings. However, attention to version policy is also required, and this feature provides precise version settings for HTTP connections. + Essentially, this feature promotes the use of HTTP protocols beyond 1.0/1.1, such as HTTP/2 or even HTTP/3. + For additional details, refer to PR #1673. -**Finally**, the [validation rules](https://github.com/ThreeMammals/Ocelot/blob/23.2.0/src/Ocelot/Configuration/Validator/FileConfigurationFluentValidator.cs#L45-L50) resulted from the incorrect assumption that placeholders are always explicit and can be validated early. Therefore, custom implementations and feature services in the dependency injection (DI) container, which rely on or manipulate placeholders, should validate the configuration JSON and appropriate options later, directly within their service implementations. +- **[Configuration](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/configuration.rst)**: Introducing the new "[Route Metadata](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/configuration.rst#route-metadata)" feature by @vantm. + Undoubtedly, this is the standout feature of the release! ⭐ Route metadata enables Ocelot developers to incorporate custom functions that address specific needs or to create their own plugins/extensions. + In versions of Ocelot prior to [{0}](https://github.com/ThreeMammals/Ocelot/releases/tag/{0}), the configuration was limited to predefined values that Ocelot used internally. This was sufficient for official extensions, but posed challenges for third-party developers who needed to implement configurations not included in the standard `FileConfiguration`. Applying an option to a specific route required knowledge of the array index and other details that might not be readily accessible using the standard `IConfiguration` or `IOptions` models from ASP.NET. Now, metadata can be directly accessed in the `DownstreamRoute` object. Furthermore, metadata can also be retrieved from the global JSON section via the `FileConfiguration.GlobalConfiguration` property. + For more information, see the details in PR #1843 on this remarkable feature. -### Bug Artifacts -- Released in version: [23.2.0](https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0) -- Introduced in: PR #1927 -- Reported bug: #2031 by @ggnaegi and tested by @Fabman08 -- Hotfix PR: #2032 by @raman-m +### Focus On + +
+ Updates of the features: Configuration, Service Discovery, Routing and Quality of Service + + - [Configuration](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/configuration.rst): New features are "[Custom Default Version Policy](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/configuration.rst#downstreamhttpversionpolicy-3)" by @ibnuda and "[Route Metadata](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/configuration.rst#route-metadata)" by @vantm. + + - [Service Discovery](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/servicediscovery.rst): New feature is "[Customization of services creation](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/servicediscovery.rst#consul-service-builder-3)" by @raman-m. + + - [Routing](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/routing.rst): New feature is "[Routing based on Request Header](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/routing.rst#upstream-headers-3)" by @jlukawska. + + - [Quality of Service](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/qualityofservice.rst): The team has decided to remove the Polly V7 policies logic and the corresponding Ocelot `AddPollyV7` extensions (referenced in PR #2079). Furthermore, the Polly V8 Circuit Breaker has been mandated as the primary strategy (as per PR #2086). + See more detaild below in "**Ocelot extra packages**" paragraph. +
+ +
+ Ocelot extra packages + + - **[Ocelot.Provider.Polly](https://www.nuget.org/packages/Ocelot.Provider.Polly)** + + - Our team has resolved to eliminate the Polly V7 policies logic and the corresponding Ocelot `AddPollyV7` extensions entirely (refer to the "[Polly v7 vs v8](https://github.com/ThreeMammals/Ocelot/blob/23.2.0/docs/features/qualityofservice.rst#polly-v7-vs-v8)" documentation). In the previous [23.2](https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0) release, named [Lunar Eclipse](https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0), we included these to maintain the legacy Polly behavior, allowing development teams to transition or retain the old Polly V7 functionality. We are now confident that it is time to progress alongside Polly, shifting our focus to the new Polly V8 [resilience pipelines](https://www.pollydocs.org/pipelines/). For more details, see PR #2079. + + - Additionally, we have implemented Polly v8 Circuit Breaker as the primary strategy. Our Quality of Service (QoS) relies on two main strategies: [Circuit Breaker](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/qualityofservice.rst#circuit-breaker-strategy) and [Timeout](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/qualityofservice.rst#timeout-strategy). If both Circuit Breaker and Timeout are [configured](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/qualityofservice.rst#configuration) with their respective properties in the `QoSOptions` of the route JSON, then the Circuit Breaker strategy will take precedence in the constructed resilience pipeline. For more details, refer to PR #2086. +
+ +
+ Stabilization aka bug fixing + + - Fixed #2034 in PR #2045 by @raman-m + - Fixed #2039 in PR #2050 by @PaulARoy + - Fixed #1590 in PR #1592 by @sergio-str + - Fixed #2054 #2059 in PR #2058 by @thiagoloureiro + - Fixed #954 #957 #1026 in PR #2067 by @raman-m + - Fixed #2002 in PR #2003 by @bbenameur + - Fixed #2085 in PR #2086 by @RaynaldM + - See [all bugs](https://github.com/ThreeMammals/Ocelot/issues?q=is%3Aissue+milestone%3ASpring%2724+is%3Aclosed+label%3Abug) of the [Spring'24](https://github.com/ThreeMammals/Ocelot/milestone/6) milestone +
+ +
+ Documentation for version {0} + + - [Caching](https://ocelot.readthedocs.io/en/{0}/features/caching.html): New [EnableContentHashing option](https://ocelot.readthedocs.io/en/{0}/features/caching.html#enablecontenthashing-option) and [Global Configuration](https://ocelot.readthedocs.io/en/{0}/features/caching.html#global-configuration) sections + - [Configuration](https://ocelot.readthedocs.io/en/{0}/features/configuration.html): New [DownstreamHttpVersionPolicy](https://ocelot.readthedocs.io/en/{0}/features/configuration.html#downstreamhttpversionpolicy-3) and [Route Metadata](https://ocelot.readthedocs.io/en/{0}/features/configuration.html#route-metadata) + - [Kubernetes](https://ocelot.readthedocs.io/en/{0}/features/kubernetes.html): New [Downstream Scheme vs Port Names](https://ocelot.readthedocs.io/en/{0}/features/kubernetes.html#downstream-scheme-vs-port-names-3) section + - [Metadata](https://ocelot.readthedocs.io/en/{0}/features/metadata.html): This is new chapter for [Route Metadata](https://ocelot.readthedocs.io/en/{0}/features/configuration.html#route-metadata) feature. + - [Quality of Service](https://ocelot.readthedocs.io/en/{0}/features/qualityofservice.html) + - [Rate Limiting](https://ocelot.readthedocs.io/en/{0}/features/ratelimiting.html) + - [Request Aggregation](https://ocelot.readthedocs.io/en/{0}/features/requestaggregation.html) + - [Routing](https://ocelot.readthedocs.io/en/{0}/features/routing.html): New [Upstream Headers](https://ocelot.readthedocs.io/en/{0}/features/routing.html#upstream-headers-3) section + - [Service Discovery](https://ocelot.readthedocs.io/en/{0}/features/servicediscovery.html): New [Consul Service Builder](https://ocelot.readthedocs.io/en/{0}/features/servicediscovery.html#consul-service-builder-3) section +
diff --git a/build.cake b/build.cake index a8f7cc362..97d2fcaa1 100644 --- a/build.cake +++ b/build.cake @@ -312,11 +312,11 @@ Task("CreateReleaseNotes") } } // END of Top 3 - // releaseNotes.Add("### Honoring :medal_sports: aka Top Contributors :clap:"); - // releaseNotes.AddRange(topContributors); - // releaseNotes.Add(""); - // releaseNotes.Add("### Starring :star: aka Release Influencers :bowtie:"); - // releaseNotes.AddRange(starring); + releaseNotes.Add("### Honoring :medal_sports: aka Top Contributors :clap:"); + releaseNotes.AddRange(topContributors); + releaseNotes.Add(""); + releaseNotes.Add("### Starring :star: aka Release Influencers :bowtie:"); + releaseNotes.AddRange(starring); releaseNotes.Add(""); releaseNotes.Add($"### Features in Release {releaseVersion}"); var commitsHistory = GitHelper($"log --no-merges --date=format:\"%A, %B %d at %H:%M\" --pretty=format:\"%h by **%aN** on %ad →%n%s\" {lastRelease}..HEAD"); diff --git a/docs/conf.py b/docs/conf.py index 6d08568ce..2c31a6b98 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,7 +9,7 @@ project = 'Ocelot' copyright = ' 2016-2024 ThreeMammals Ocelot team' author = 'Tom Pallister, Raman Maksimchuk and Ocelot Core team at ThreeMammals' -release = '23.2' +release = '23.3' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration diff --git a/docs/features/caching.rst b/docs/features/caching.rst index 84803060f..3d14b47c9 100644 --- a/docs/features/caching.rst +++ b/docs/features/caching.rst @@ -49,6 +49,8 @@ The **Region** represents a region of caching. Additionally, if a header name is defined in the **Header** property, that header value is looked up by the key (header name) in the ``HttpRequest`` headers, and if the header is found, its value will be included in caching key. This causes the cache to become invalid due to the header value changing. +.. _cch-enablecontenthashing-option: + ``EnableContentHashing`` option ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/features/configuration.rst b/docs/features/configuration.rst index 5a29a6b48..1be532e08 100644 --- a/docs/features/configuration.rst +++ b/docs/features/configuration.rst @@ -447,6 +447,8 @@ You can utilize these methods in the ``ConfigureAppConfiguration`` method (locat You can find additional details in the dedicated :ref:`di-configuration-overview` section and in subsequent sections related to the :doc:`../features/dependencyinjection` chapter. +.. _config-route-metadata: + Route Metadata -------------- diff --git a/docs/features/kubernetes.rst b/docs/features/kubernetes.rst index 8c6967c87..8bbdb1881 100644 --- a/docs/features/kubernetes.rst +++ b/docs/features/kubernetes.rst @@ -117,6 +117,8 @@ If your downstream service resides in a different namespace, you can override th } ] +.. _k8s-downstream-scheme-vs-port-names: + Downstream Scheme vs Port Names [#f3]_ -------------------------------------- diff --git a/docs/features/qualityofservice.rst b/docs/features/qualityofservice.rst index 4fa4ecf9c..fde699ddf 100644 --- a/docs/features/qualityofservice.rst +++ b/docs/features/qualityofservice.rst @@ -23,6 +23,8 @@ Next, within your ``ConfigureServices`` method, to incorporate `Polly`_ services services.AddOcelot() .AddPolly(); +.. _qos-configuration: + Configuration ------------- @@ -40,6 +42,8 @@ Then add the following section to a Route configuration: - ``DurationOfBreak`` means the circuit breaker will stay open for 1 second after it is tripped. - ``TimeoutValue`` means if a request takes more than 5 seconds, it will automatically be timed out. +.. _qos-circuit-breaker-strategy: + Circuit Breaker strategy ------------------------ @@ -62,6 +66,8 @@ Alternatively, you may omit ``DurationOfBreak`` to default to the implicit 5 sec This setup activates only the `Circuit breaker `_ strategy. +.. _qos-timeout-strategy: + Timeout strategy ---------------- diff --git a/docs/index.rst b/docs/index.rst index c313c5104..a70eefdbc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,13 +1,49 @@ .. _Polly: https://github.com/App-vNext/Polly -.. _@ebjornset: https://github.com/ebjornset -.. _@RaynaldM: https://github.com/RaynaldM -.. _@ArwynFr: https://github.com/ArwynFr -.. _@AlyHKafoury: https://github.com/AlyHKafoury -.. _@FelixBoers: https://github.com/FelixBoers -.. _23.2: https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0 +.. _Circuit Breaker: https://www.pollydocs.org/strategies/circuit-breaker.html +.. _Timeout: https://www.pollydocs.org/strategies/timeout.html -Welcome to Ocelot `23.2`_ -====================================================================================== +.. _@raman-m: https://github.com/raman-m +.. _@RaynaldM: https://github.com/RaynaldM +.. _@jlukawska: https://github.com/jlukawska +.. _@ibnuda: https://github.com/ibnuda +.. _@vantm: https://github.com/vantm +.. _@sergio-str: https://github.com/sergio-str +.. _@PaulARoy: https://github.com/PaulARoy +.. _@thiagoloureiro: https://github.com/thiagoloureiro +.. _@bbenameur: https://github.com/bbenameur + +.. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0 +.. _23.3.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0 +.. _23.2.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0 + +.. _954: https://github.com/ThreeMammals/Ocelot/issues/954 +.. _957: https://github.com/ThreeMammals/Ocelot/issues/957 +.. _1026: https://github.com/ThreeMammals/Ocelot/issues/1026 +.. _1312: https://github.com/ThreeMammals/Ocelot/pull/1312 +.. _1590: https://github.com/ThreeMammals/Ocelot/issues/1590 +.. _1592: https://github.com/ThreeMammals/Ocelot/pull/1592 +.. _1673: https://github.com/ThreeMammals/Ocelot/pull/1673 +.. _1843: https://github.com/ThreeMammals/Ocelot/pull/1843 +.. _2002: https://github.com/ThreeMammals/Ocelot/issues/2002 +.. _2003: https://github.com/ThreeMammals/Ocelot/pull/2003 +.. _2034: https://github.com/ThreeMammals/Ocelot/issues/2034 +.. _2039: https://github.com/ThreeMammals/Ocelot/issues/2039 +.. _2045: https://github.com/ThreeMammals/Ocelot/pull/2045 +.. _2050: https://github.com/ThreeMammals/Ocelot/pull/2050 +.. _2052: https://github.com/ThreeMammals/Ocelot/pull/2052 +.. _2054: https://github.com/ThreeMammals/Ocelot/discussions/2054 +.. _2058: https://github.com/ThreeMammals/Ocelot/pull/2058 +.. _2059: https://github.com/ThreeMammals/Ocelot/issues/2059 +.. _2067: https://github.com/ThreeMammals/Ocelot/pull/2067 +.. _2079: https://github.com/ThreeMammals/Ocelot/pull/2079 +.. _2085: https://github.com/ThreeMammals/Ocelot/issues/2085 +.. _2086: https://github.com/ThreeMammals/Ocelot/pull/2086 + +.. role:: htm(raw) + :format: html + +Welcome to Ocelot `23.3`_ +========================= Thanks for taking a look at the Ocelot documentation! Please use the left hand navigation to get around. The team would suggest taking a look at the **Introduction** chapter first. @@ -20,67 +56,108 @@ We **do** follow development process which is described in :doc:`../building/rel Release Notes ------------- - | **Release Tag**: `23.2.0 `_ - | **Release Codename**: `Lunar Eclipse `_ +| Release Tag: `23.3.0`_ +| Release Codename: **Twilight Texas** + :htm:`→` `for men `_ + :htm:`→` `for women `_ + :htm:`→` `for black men `_ What's new? ^^^^^^^^^^^ -- :doc:`../features/configuration`: A brand new :ref:`config-merging-tomemory` by `@ebjornset`_ as a part of the :ref:`config-merging-files` feature. - - The ``AddOcelot`` method merges the **ocelot.*.json** files into a single **ocelot.json** file as the primary configuration file, which is written back to disk and then added to the ``IConfigurationBuilder`` for the well-known ``IConfiguration``. You can now call another ``AddOcelot`` method that adds the merged JSON directly from memory to the ``IConfigurationBuilder``, using ``AddJsonStream`` instead. - - See more details in :ref:`di-configuration-overview` of :doc:`../features/dependencyinjection`. +- :doc:`../features/servicediscovery`: Introducing a new feature for "*Customization of services creation*" in two primary service discovery providers: ``Consul`` (:ref:`sd-consul-service-builder`) and ``Kubernetes`` (:ref:`k8s-downstream-scheme-vs-port-names`), developed by `@raman-m`_. + + The customization for both ``Consul`` and ``Kube`` providers in service creation is achieved through the overriding of virtual methods in default implementations. The recommendation was to separate the provider's logic and introduce ``public virtual`` and ``protected virtual`` methods in concrete classes, enabling: + + - The use of ``public virtual`` methods as dictated by interface definitions. + - The application of ``protected virtual`` methods to allow developers to customize atomic operations through inheritance from existing concrete classes. + - The injection of new interface objects into the provider's constructor. + - The overriding of the default behavior of classes. + + | Ultimately, customization relies on the virtual methods within the default implementation classes, providing developers the flexibility to override them as necessary for highly tailored Consul/K8s configurations in their specific environments. + | For further details, refer to the respective pull requests for both providers: + + - ``Kube`` :htm:`→` PR `2052`_ + - ``Consul`` :htm:`→` PR `2067`_ + +- :doc:`../features/routing`: Introducing the new ":ref:`routing-upstream-headers`" feature by `@jlukawska`_. + + | In addition to routing via ``UpstreamPathTemplate``, you can now define an ``UpstreamHeaderTemplates`` options dictionary. For a route to match, all headers specified in this section are required to be present in the request headers. + | For more details, see PR `1312`_. + +- :doc:`../features/configuration`: Introducing the ":ref:`config-version-policy`" feature by `@ibnuda`_. + + The configurable ``HttpRequestMessage.VersionPolicy`` helps avoid HTTP protocol connection errors and stabilizes connections to downstream services, especially when you're not developing those services, documentation is scarce, or the deployed HTTP protocol version is uncertain. + For developers of downstream services, it's possible to ``ConfigureKestrel`` server and its endpoints with new protocol settings. However, attention to version policy is also required, and this feature provides precise version settings for HTTP connections. + + | Essentially, this feature promotes the use of HTTP protocols beyond 1.0/1.1, such as HTTP/2 or even HTTP/3. + | For additional details, refer to PR `1673`_. -- :doc:`../features/servicefabric`: Published old undocumented :ref:`sf-placeholders` feature of :doc:`../features/servicefabric` `service discovery provider `_. +- :doc:`../features/configuration`: Introducing the new ":ref:`config-route-metadata`" feature by `@vantm`_. - This feature by `@FelixBoers`_ is available starting from version `13.0.0 `_. + Undoubtedly, this is the standout feature of the release! ⭐ -- :doc:`../features/qualityofservice`: A brand new `Polly`_ v8 pipelines :ref:`qos-extensibility` feature by `@RaynaldM`_ + Route metadata enables Ocelot developers to incorporate custom functions that address specific needs or to create their own plugins/extensions. + + In versions of Ocelot prior to `23.3.0`_, the configuration was limited to predefined values that Ocelot used internally. This was sufficient for official extensions, but posed challenges for third-party developers who needed to implement configurations not included in the standard ``FileConfiguration``. + Applying an option to a specific route required knowledge of the array index and other details that might not be readily accessible using the standard ``IConfiguration`` or ``IOptions`` models from ASP.NET. + + | Now, :doc:`../features/metadata` can be directly accessed in the ``DownstreamRoute`` object. Furthermore, metadata can also be retrieved from the global JSON section via the ``FileConfiguration.GlobalConfiguration`` property. + | For more information, see the details in PR `1843`_ on this remarkable feature. Focus On ^^^^^^^^ Updates of the features """"""""""""""""""""""" - - - :doc:`../features/configuration`: New :ref:`config-merging-tomemory` feature by `@ebjornset`_ - - :doc:`../features/dependencyinjection`: Added new overloaded :ref:`di-configuration-addocelot` by `@ebjornset`_ - - :doc:`../features/qualityofservice`: Support of new `Polly`_ v8 syntax and new :ref:`qos-extensibility` feature by `@RaynaldM`_ + +- :doc:`../features/configuration`: New features are ":ref:`config-version-policy`" by `@ibnuda`_ and ":ref:`config-route-metadata`" by `@vantm`_. +- :doc:`../features/servicediscovery`: New feature is "*Customization of services creation*" aka :ref:`sd-consul-service-builder` and :ref:`k8s-downstream-scheme-vs-port-names` by `@raman-m`_. +- :doc:`../features/routing`: New feature is ":ref:`routing-upstream-headers`" by `@jlukawska`_. +- :doc:`../features/qualityofservice`: The team has decided to remove the Polly V7 policies logic and the corresponding Ocelot ``AddPollyV7`` extensions (referenced in PR `2079`_). + + | Furthermore, the Polly V8 Circuit Breaker has been mandated as the primary strategy (as per PR `2086`_). + | See more detaild below in "**Ocelot extra packages**" paragraph. Ocelot extra packages """"""""""""""""""""" - - `Ocelot.Provider.Polly `_: Support of new `Polly`_ v8 syntax. +- `Ocelot.Provider.Polly `_ - | *Polly* `8.0+ `_ versions introduced the concept of `resilience pipelines `_. - | All `AddPolly extensions `_ have been automatically migrated from **v7** to **v8**. - | Please note that older **v7** extensions are marked with the ``[Obsolete]`` attribute and renamed using the ``V7`` suffix. And the old **v7** implementation has been moved to the `v7 namespace `_. - | See more details in :ref:`qos-polly-v7-vs-v8` section of :doc:`../features/qualityofservice` chapter. + - Our team has resolved to eliminate the Polly V7 policies logic and the corresponding Ocelot ``AddPollyV7`` extensions entirely (refer to the "`Polly v7 vs v8 `_" documentation). + In the previous `23.2.0`_ release, named `Lunar Eclipse `_, we included these to maintain the legacy `Polly`_ behavior, allowing development teams to transition or retain the old Polly V7 functionality. + We are now confident that it is time to progress alongside `Polly`_, shifting our focus to the new `Polly V8 `_ `resilience pipelines `_. + For more details, see PR `2079`_. + - Additionally, we have implemented Polly v8 `Circuit Breaker `_ as the primary strategy. + Our :doc:`../features/qualityofservice` (QoS) relies on two main strategies: :ref:`qos-circuit-breaker-strategy` and :ref:`qos-timeout-strategy`. + If both `Circuit Breaker`_ and `Timeout`_ have :ref:`qos-configuration` with their respective properties in the ``QoSOptions`` of the route JSON, then the :ref:`qos-circuit-breaker-strategy` will take precedence in the constructed resilience pipeline. + For more details, refer to PR `2086`_. Stabilization aka bug fixing """""""""""""""""""""""""""" - - `683 `_ by PR `1927 `_. Thanks to `@AlyHKafoury`_! - - | `New rules `_ have been added to Ocelot's configuration validation logic to find duplicate placeholders in path templates. - | See more in the `FileConfigurationFluentValidator `_ class. - - - `1518 `_ hotfix by PR `1986 `_. Thanks to `@ArwynFr`_! - - | Using the default ``IServiceCollection`` `DI extensions `_ to register Ocelot services resulted in the ``ServiceCollection`` provider being forced to be created by calling ``BuildServiceProvider()``. - | This resulted in problems with dependency injection libraries, or worse, causing the Ocelot app to crash! - | See more in the `ServiceCollectionExtensions `_ class. - - - See `all bugs `_ of the `February'24 `_ milestone - -Updated Documentation -""""""""""""""""""""" - - - :doc:`../features/configuration` - - :doc:`../features/dependencyinjection` - - :doc:`../features/qualityofservice` - - :doc:`../features/servicefabric` +- Fixed `2034`_ in PR `2045`_ by `@raman-m`_ +- Fixed `2039`_ in PR `2050`_ by `@PaulARoy`_ +- Fixed `1590`_ in PR `1592`_ by `@sergio-str`_ +- Fixed `2054`_ `2059`_ in PR `2058`_ by `@thiagoloureiro`_ +- Fixed `954`_ `957`_ `1026`_ in PR `2067`_ by `@raman-m`_ +- Fixed `2002`_ in PR `2003`_ by `@bbenameur`_ +- Fixed `2085`_ in PR `2086`_ by `@RaynaldM`_ + +See `all bugs `_ of the `Spring'24 `_ milestone + +Documentation for version `23.3`_ +""""""""""""""""""""""""""""""""" + +- :doc:`../features/caching`: New :ref:`cch-enablecontenthashing-option` and :ref:`cch-global-configuration` sections +- :doc:`../features/configuration`: New :ref:`config-version-policy` and :ref:`config-route-metadata` sections +- :doc:`../features/kubernetes`: New :ref:`k8s-downstream-scheme-vs-port-names` section +- :doc:`../features/metadata`: This is new chapter for :ref:`config-route-metadata` feature +- :doc:`../features/qualityofservice` +- :doc:`../features/ratelimiting` +- :doc:`../features/requestaggregation` +- :doc:`../features/routing`: New :ref:`routing-upstream-headers` section +- :doc:`../features/servicediscovery`: New :ref:`sd-consul-service-builder` and :ref:`k8s-downstream-scheme-vs-port-names` sections .. toctree::