From 6229e44e9329bc3495f5ee0d862bde0fd8ad0d4d Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Thu, 10 Oct 2024 19:19:37 +0300 Subject: [PATCH 01/13] index.rst patch --- docs/conf.py | 4 ++-- docs/index.rst | 42 ++++++++++++++++++------------------------ 2 files changed, 20 insertions(+), 26 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 2c31a6b98..0ee169424 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,9 +6,9 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'Ocelot' +project = 'Ocelot Gateway' copyright = ' 2016-2024 ThreeMammals Ocelot team' -author = 'Tom Pallister, Raman Maksimchuk and Ocelot Core team at ThreeMammals' +author = 'Tom Pallister, Raman Maksimchuk' release = '23.3' # -- General configuration --------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 562646151..a165832e6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,19 +44,22 @@ .. role:: htm(raw) :format: html -Welcome to Ocelot `23.3`_ -========================= +############################ +Ocelot `23.3`_ Documentation +############################ -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. +Thanks for taking a look at the Ocelot documentation! -All **Features** are arranged in alphabetical order. -The main features are :doc:`../features/configuration` and :doc:`../features/routing`. +Please use the left hand **Navigation** bar to get around. +The team would suggest taking a look at the **Introduction** chapters first. -We **do** follow development process which is described in :doc:`../building/releaseprocess`. +All **Features** are listed in alphabetical order. +The primary features include :doc:`../features/configuration` and :doc:`../features/routing`. -Patches -------- +*We adhere to a development process* outlined in :doc:`../building/releaseprocess`. +Additional tips for building Ocelot can be found in the **Building Ocelot** section. + +:htm:`

Patches

` - `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. - `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. @@ -70,8 +73,7 @@ Patches :htm:`` -Release Notes -------------- +:htm:`

Release Notes

` | Release Tag: `23.3.0`_ | Release Codename: `Twilight Texas `_ @@ -84,8 +86,7 @@ Release Notes :htm:`` -What's new? -^^^^^^^^^^^ +:htm:`

What's new?

` - :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`_. @@ -127,11 +128,7 @@ What's new? | 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 -""""""""""""""""""""""" +:htm:`

Updates of the features

` - :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`_. @@ -141,8 +138,7 @@ Updates of the features | 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 -""""""""""""""""""""" +:htm:`

Ocelot extra packages

` - `Ocelot.Provider.Polly `_ @@ -155,8 +151,7 @@ Ocelot extra packages 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 (bug fixing) -^^^^^^^^^^^^^^^^^^^^^^^^^^ +:htm:`

Stabilization (bug fixing)

` - Fixed `2034`_ in PR `2045`_ by `@raman-m`_ - Fixed `2039`_ in PR `2050`_ by `@PaulARoy`_ @@ -168,8 +163,7 @@ Stabilization (bug fixing) See `all bugs `_ of the `Spring'24 `_ milestone -Documentation Summary -^^^^^^^^^^^^^^^^^^^^^ +:htm:`

Documentation Summary

` - :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 From 529846e947ef55d2c3a221fe017fb242b9c96615 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Thu, 10 Oct 2024 21:16:25 +0300 Subject: [PATCH 02/13] index.rst patch 2 --- docs/index.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index a165832e6..195520643 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -178,9 +178,9 @@ See `all bugs Date: Fri, 11 Oct 2024 13:01:52 +0300 Subject: [PATCH 03/13] patch 3 --- docs/conf.py | 2 +- docs/index.rst | 124 +++++++++++++++++++++++++++---------------------- 2 files changed, 69 insertions(+), 57 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0ee169424..c0de181d8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,7 +7,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'Ocelot Gateway' -copyright = ' 2016-2024 ThreeMammals Ocelot team' +copyright = '2016-%Y, ThreeMammals Ocelot team' author = 'Tom Pallister, Raman Maksimchuk' release = '23.3' diff --git a/docs/index.rst b/docs/index.rst index 195520643..24db7ffa7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,20 +44,84 @@ .. role:: htm(raw) :format: html -############################ +============================ Ocelot `23.3`_ Documentation -############################ +============================ Thanks for taking a look at the Ocelot documentation! +Please use the left hand **Navigation** sidebar to get around. + +.. _Introduction: + +Introduction +============ -Please use the left hand **Navigation** bar to get around. The team would suggest taking a look at the **Introduction** chapters first. +.. toctree:: + :maxdepth: 2 + :caption: Introduction + + introduction/welcome + introduction/bigpicture + introduction/gettingstarted + introduction/contributing + introduction/notsupported + introduction/gotchas + + +Features +======== + All **Features** are listed in alphabetical order. The primary features include :doc:`../features/configuration` and :doc:`../features/routing`. -*We adhere to a development process* outlined in :doc:`../building/releaseprocess`. +.. toctree:: + :maxdepth: 2 + :caption: Features + + features/administration + features/authentication + features/authorization + features/caching + features/claimstransformation + features/configuration + features/delegatinghandlers + features/dependencyinjection + features/errorcodes + features/graphql + features/headerstransformation + features/kubernetes + features/loadbalancer + features/logging + features/metadata + features/methodtransformation + features/middlewareinjection + features/qualityofservice + features/ratelimiting + features/requestaggregation + features/requestid + features/routing + features/servicediscovery + features/servicefabric + features/tracing + features/websockets + + +Building Ocelot +=============== + Additional tips for building Ocelot can be found in the **Building Ocelot** section. +We adhere to a development process outlined in :doc:`../building/releaseprocess`. + +.. toctree:: + :maxdepth: 2 + :caption: Building Ocelot + + building/overview + building/building + building/tests + building/releaseprocess :htm:`

Patches

` @@ -174,55 +238,3 @@ See `all bugs Date: Fri, 11 Oct 2024 13:33:36 +0300 Subject: [PATCH 04/13] patch 4 --- docs/index.rst | 172 +-------------------------------- docs/introduction/welcome.rst | 174 ++++++++++++++++++++++++++++++++++ 2 files changed, 175 insertions(+), 171 deletions(-) create mode 100644 docs/introduction/welcome.rst diff --git a/docs/index.rst b/docs/index.rst index 24db7ffa7..35331e9c6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,60 +1,11 @@ -.. _Polly: https://github.com/App-vNext/Polly -.. _Circuit Breaker: https://www.pollydocs.org/strategies/circuit-breaker.html -.. _Timeout: https://www.pollydocs.org/strategies/timeout.html - -.. _@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.2.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0 -.. _23.3.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0 -.. _23.3.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.3 -.. _23.3.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 .. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 -.. _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 - ============================ Ocelot `23.3`_ Documentation ============================ Thanks for taking a look at the Ocelot documentation! -Please use the left hand **Navigation** sidebar to get around. - -.. _Introduction: - -Introduction -============ +Please use the left hand **Navigation** sidebar to get around, or see Table of Contents below. The team would suggest taking a look at the **Introduction** chapters first. @@ -70,9 +21,6 @@ The team would suggest taking a look at the **Introduction** chapters first. introduction/gotchas -Features -======== - All **Features** are listed in alphabetical order. The primary features include :doc:`../features/configuration` and :doc:`../features/routing`. @@ -108,9 +56,6 @@ The primary features include :doc:`../features/configuration` and :doc:`../featu features/websockets -Building Ocelot -=============== - Additional tips for building Ocelot can be found in the **Building Ocelot** section. We adhere to a development process outlined in :doc:`../building/releaseprocess`. @@ -123,118 +68,3 @@ We adhere to a development process outlined in :doc:`../building/releaseprocess` building/tests building/releaseprocess -:htm:`

Patches

` - -- `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. -- `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. - - :htm:`
Codename decoding links` - - - **for men** :htm:`→` naked `Blue Olympic Fiend `_ - - **for women** :htm:`→` not a well-dressed woman sings at the opening ceremony, so "Not `Celine Dion `_" - - **for black men** :htm:`→` don't care about White movements, so enjoy `Black Men's Basketball Final `_ in `Paris 2024 `_: - be proud of Stephen Curry, "just give me a ball" boy, as an absolute rockstar, made `shot 1 `_, `shot 2 `_, `shot 3 `_ and final `shot 4 `_. - - :htm:`
` - -:htm:`

Release Notes

` - -| Release Tag: `23.3.0`_ -| Release Codename: `Twilight Texas `_ - - :htm:`
Codename decoding links` - - - `for men `_ - - `for women `_ - - `for black men `_ - - :htm:`
` - -:htm:`

What's new?

` - -- :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/configuration`: Introducing the new ":ref:`config-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 `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. - -:htm:`

Updates of the features

` - -- :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. - -:htm:`

Ocelot extra 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 `_" 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`_. - -:htm:`

Stabilization (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 `_ of the `Spring'24 `_ milestone - -:htm:`

Documentation Summary

` - -- :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 diff --git a/docs/introduction/welcome.rst b/docs/introduction/welcome.rst new file mode 100644 index 000000000..c7d2ea4f2 --- /dev/null +++ b/docs/introduction/welcome.rst @@ -0,0 +1,174 @@ +.. _Polly: https://github.com/App-vNext/Polly +.. _Circuit Breaker: https://www.pollydocs.org/strategies/circuit-breaker.html +.. _Timeout: https://www.pollydocs.org/strategies/timeout.html + +.. _@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.2.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0 +.. _23.3.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0 +.. _23.3.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.3 +.. _23.3.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 +.. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 + +.. _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 +======= + +Abc... + +Patches +------- + +- `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. +- `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. + + :htm:`
Codename decoding links` + + - **for men** :htm:`→` naked `Blue Olympic Fiend `_ + - **for women** :htm:`→` not a well-dressed woman sings at the opening ceremony, so "Not `Celine Dion `_" + - **for black men** :htm:`→` don't care about White movements, so enjoy `Black Men's Basketball Final `_ in `Paris 2024 `_: + be proud of Stephen Curry, "just give me a ball" boy, as an absolute rockstar, made `shot 1 `_, `shot 2 `_, `shot 3 `_ and final `shot 4 `_. + + :htm:`
` + +Release Notes +------------- + +| Release Tag: `23.3.0`_ +| Release Codename: `Twilight Texas `_ + + :htm:`
Codename decoding links` + + - `for men `_ + - `for women `_ + - `for black men `_ + + :htm:`
` + +What's new? +^^^^^^^^^^^ + +- :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/configuration`: Introducing the new ":ref:`config-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 `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. + +Updates of the features +^^^^^^^^^^^^^^^^^^^^^^^ + +- :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 `_ + + - 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 (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 `_ of the `Spring'24 `_ milestone + +Documentation Summary +^^^^^^^^^^^^^^^^^^^^^ + +- :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 From 82912e976459d086defbd3cb361d91650066dda3 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Fri, 11 Oct 2024 14:32:12 +0300 Subject: [PATCH 05/13] patch 5 --- docs/conf.py | 15 +++++++++++++-- docs/index.rst | 42 +++++++++++++++++++++++++++++++----------- 2 files changed, 44 insertions(+), 13 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index c0de181d8..547d0b5a6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,14 +7,25 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'Ocelot Gateway' -copyright = '2016-%Y, ThreeMammals Ocelot team' +copyright = ' 2016-%Y, ThreeMammals Ocelot team' author = 'Tom Pallister, Raman Maksimchuk' release = '23.3' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = [] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.todo', + 'sphinx.ext.autosummary', + 'sphinx.ext.extlinks', + 'sphinx.ext.intersphinx', + 'sphinx.ext.viewcode', + 'sphinx.ext.inheritance_diagram', + 'sphinx.ext.coverage', + 'sphinx.ext.graphviz', +] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] diff --git a/docs/index.rst b/docs/index.rst index 35331e9c6..4fb7b2583 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,3 +1,7 @@ +.. _23.2.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0 +.. _23.3.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0 +.. _23.3.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.3 +.. _23.3.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 .. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 ============================ @@ -9,9 +13,33 @@ Please use the left hand **Navigation** sidebar to get around, or see Table of C The team would suggest taking a look at the **Introduction** chapters first. +All **Features** are listed in alphabetical order. +The primary features include :doc:`../features/configuration` and :doc:`../features/routing`. + +Additional tips for building Ocelot can be found in the **Building Ocelot** section. +We adhere to a development process outlined in :doc:`../building/releaseprocess`. + +Patches +------- + +- `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. +- `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. + + :htm:`
Codename decoding links` + + - **for men** :htm:`→` naked `Blue Olympic Fiend `_ + - **for women** :htm:`→` not a well-dressed woman sings at the opening ceremony, so "Not `Celine Dion `_" + - **for black men** :htm:`→` don't care about White movements, so enjoy `Black Men's Basketball Final `_ in `Paris 2024 `_: + be proud of Stephen Curry, "just give me a ball" boy, as an absolute rockstar, made `shot 1 `_, `shot 2 `_, `shot 3 `_ and final `shot 4 `_. + + :htm:`
` + +Table of Contents +----------------- + .. toctree:: - :maxdepth: 2 :caption: Introduction + :numbered: introduction/welcome introduction/bigpicture @@ -20,13 +48,9 @@ The team would suggest taking a look at the **Introduction** chapters first. introduction/notsupported introduction/gotchas - -All **Features** are listed in alphabetical order. -The primary features include :doc:`../features/configuration` and :doc:`../features/routing`. - .. toctree:: - :maxdepth: 2 :caption: Features + :numbered: features/administration features/authentication @@ -55,13 +79,9 @@ The primary features include :doc:`../features/configuration` and :doc:`../featu features/tracing features/websockets - -Additional tips for building Ocelot can be found in the **Building Ocelot** section. -We adhere to a development process outlined in :doc:`../building/releaseprocess`. - .. toctree:: - :maxdepth: 2 :caption: Building Ocelot + :numbered: building/overview building/building From c5f51f41e023db4af2e5663388c07f5da75852d4 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Fri, 11 Oct 2024 15:18:04 +0300 Subject: [PATCH 06/13] patch 6 --- docs/conf.py | 12 +---- docs/index.rst | 123 ++++++++++++++++++++++--------------------------- 2 files changed, 56 insertions(+), 79 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 547d0b5a6..1cfc5e4a3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,7 +7,7 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information project = 'Ocelot Gateway' -copyright = ' 2016-%Y, ThreeMammals Ocelot team' +copyright = ' 2016-2024, ThreeMammals Ocelot team' author = 'Tom Pallister, Raman Maksimchuk' release = '23.3' @@ -15,16 +15,6 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'sphinx.ext.todo', - 'sphinx.ext.autosummary', - 'sphinx.ext.extlinks', - 'sphinx.ext.intersphinx', - 'sphinx.ext.viewcode', - 'sphinx.ext.inheritance_diagram', - 'sphinx.ext.coverage', - 'sphinx.ext.graphviz', ] templates_path = ['_templates'] diff --git a/docs/index.rst b/docs/index.rst index 4fb7b2583..f51cbae5e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,72 +19,59 @@ The primary features include :doc:`../features/configuration` and :doc:`../featu Additional tips for building Ocelot can be found in the **Building Ocelot** section. We adhere to a development process outlined in :doc:`../building/releaseprocess`. -Patches -------- - -- `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. -- `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. - - :htm:`
Codename decoding links` - - - **for men** :htm:`→` naked `Blue Olympic Fiend `_ - - **for women** :htm:`→` not a well-dressed woman sings at the opening ceremony, so "Not `Celine Dion `_" - - **for black men** :htm:`→` don't care about White movements, so enjoy `Black Men's Basketball Final `_ in `Paris 2024 `_: - be proud of Stephen Curry, "just give me a ball" boy, as an absolute rockstar, made `shot 1 `_, `shot 2 `_, `shot 3 `_ and final `shot 4 `_. - - :htm:`
` - -Table of Contents ------------------ - -.. toctree:: - :caption: Introduction - :numbered: - - introduction/welcome - introduction/bigpicture - introduction/gettingstarted - introduction/contributing - introduction/notsupported - introduction/gotchas - -.. toctree:: - :caption: Features - :numbered: - - features/administration - features/authentication - features/authorization - features/caching - features/claimstransformation - features/configuration - features/delegatinghandlers - features/dependencyinjection - features/errorcodes - features/graphql - features/headerstransformation - features/kubernetes - features/loadbalancer - features/logging - features/metadata - features/methodtransformation - features/middlewareinjection - features/qualityofservice - features/ratelimiting - features/requestaggregation - features/requestid - features/routing - features/servicediscovery - features/servicefabric - features/tracing - features/websockets - -.. toctree:: - :caption: Building Ocelot - :numbered: - - building/overview - building/building - building/tests - building/releaseprocess +.. admonition:: Patches + + - `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. + - `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. + + +.. admonition:: Table of Contents + + .. toctree:: + :caption: Introduction + + introduction/welcome + introduction/bigpicture + introduction/gettingstarted + introduction/contributing + introduction/notsupported + introduction/gotchas + + .. toctree:: + :caption: Features + + features/administration + features/authentication + features/authorization + features/caching + features/claimstransformation + features/configuration + features/delegatinghandlers + features/dependencyinjection + features/errorcodes + features/graphql + features/headerstransformation + features/kubernetes + features/loadbalancer + features/logging + features/metadata + features/methodtransformation + features/middlewareinjection + features/qualityofservice + features/ratelimiting + features/requestaggregation + features/requestid + features/routing + features/servicediscovery + features/servicefabric + features/tracing + features/websockets + + .. toctree:: + :caption: Building Ocelot + + building/overview + building/building + building/tests + building/releaseprocess From 2d52b4498f3898816a09bb4f0b33930924c03747 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Fri, 11 Oct 2024 18:39:53 +0300 Subject: [PATCH 07/13] patch 7 --- docs/index.rst | 25 +++++++++++++------ .../welcome.rst => releasenotes.rst} | 2 ++ 2 files changed, 19 insertions(+), 8 deletions(-) rename docs/{introduction/welcome.rst => releasenotes.rst} (98%) diff --git a/docs/index.rst b/docs/index.rst index f51cbae5e..59bfb068c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,6 +2,7 @@ .. _23.3.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0 .. _23.3.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.3 .. _23.3.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 +.. _23.3.5: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.5 .. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 ============================ @@ -23,21 +24,28 @@ We adhere to a development process outlined in :doc:`../building/releaseprocess` - `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. - `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. - + - `23.3.5`_, on Oct 11, 2024. Documentation patch: Html and Pdf doc layouts. .. admonition:: Table of Contents .. toctree:: - :caption: Introduction + :maxdepth: 2 + :caption: Welcome + + releasenotes + + .. toctree:: + :maxdepth: 3 + :caption: Introduction - introduction/welcome - introduction/bigpicture - introduction/gettingstarted - introduction/contributing - introduction/notsupported - introduction/gotchas + introduction/bigpicture + introduction/gettingstarted + introduction/contributing + introduction/notsupported + introduction/gotchas .. toctree:: + :maxdepth: 3 :caption: Features features/administration @@ -68,6 +76,7 @@ We adhere to a development process outlined in :doc:`../building/releaseprocess` features/websockets .. toctree:: + :maxdepth: 3 :caption: Building Ocelot building/overview diff --git a/docs/introduction/welcome.rst b/docs/releasenotes.rst similarity index 98% rename from docs/introduction/welcome.rst rename to docs/releasenotes.rst index c7d2ea4f2..9c9e17f9c 100644 --- a/docs/introduction/welcome.rst +++ b/docs/releasenotes.rst @@ -16,6 +16,7 @@ .. _23.3.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0 .. _23.3.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.3 .. _23.3.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 +.. _23.3.5: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.5 .. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 .. _954: https://github.com/ThreeMammals/Ocelot/issues/954 @@ -55,6 +56,7 @@ Patches - `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. - `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. +- `23.3.5`_, on Oct 11, 2024. Documentation patch: Html and Pdf doc layouts. :htm:`
Codename decoding links` From e46d015c7fab702d86c55e300852eba54d0a1488 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Fri, 11 Oct 2024 21:00:14 +0300 Subject: [PATCH 08/13] patch 8 --- docs/index.rst | 12 +++--------- docs/releasenotes.rst | 14 ++++++++------ 2 files changed, 11 insertions(+), 15 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 59bfb068c..32db35a2a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,12 +5,12 @@ .. _23.3.5: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.5 .. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4 -============================ +############################ Ocelot `23.3`_ Documentation -============================ +############################ Thanks for taking a look at the Ocelot documentation! -Please use the left hand **Navigation** sidebar to get around, or see Table of Contents below. +Please use the left hand **Navigation** sidebar to get around, or see **Table of Contents** below. The team would suggest taking a look at the **Introduction** chapters first. @@ -20,12 +20,6 @@ The primary features include :doc:`../features/configuration` and :doc:`../featu Additional tips for building Ocelot can be found in the **Building Ocelot** section. We adhere to a development process outlined in :doc:`../building/releaseprocess`. -.. admonition:: Patches - - - `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. - - `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. - - `23.3.5`_, on Oct 11, 2024. Documentation patch: Html and Pdf doc layouts. - .. admonition:: Table of Contents .. toctree:: diff --git a/docs/releasenotes.rst b/docs/releasenotes.rst index 9c9e17f9c..e64bcab58 100644 --- a/docs/releasenotes.rst +++ b/docs/releasenotes.rst @@ -45,27 +45,29 @@ .. role:: htm(raw) :format: html -======= +.. _welcome: + +####### Welcome -======= +####### Abc... +.. .. admonition:: Patches + Patches ------- - `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. - `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. -- `23.3.5`_, on Oct 11, 2024. Documentation patch: Html and Pdf doc layouts. - - :htm:`
Codename decoding links` + Codename decoding links - **for men** :htm:`→` naked `Blue Olympic Fiend `_ - **for women** :htm:`→` not a well-dressed woman sings at the opening ceremony, so "Not `Celine Dion `_" - **for black men** :htm:`→` don't care about White movements, so enjoy `Black Men's Basketball Final `_ in `Paris 2024 `_: be proud of Stephen Curry, "just give me a ball" boy, as an absolute rockstar, made `shot 1 `_, `shot 2 `_, `shot 3 `_ and final `shot 4 `_. - :htm:`
` +- `23.3.5`_, on Oct 11, 2024. Documentation patch: Html and Pdf doc layouts. Release Notes ------------- From 7f264c57c7c8950b114d444141369b3434daa522 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Sat, 12 Oct 2024 14:35:02 +0300 Subject: [PATCH 09/13] patch 9 --- docs/index.rst | 7 +++-- docs/introduction/contributing.rst | 6 ++-- docs/releasenotes.rst | 44 +++++++++++++----------------- 3 files changed, 26 insertions(+), 31 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 32db35a2a..b9d17c402 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,9 +10,10 @@ Ocelot `23.3`_ Documentation ############################ Thanks for taking a look at the Ocelot documentation! -Please use the left hand **Navigation** sidebar to get around, or see **Table of Contents** below. +Please use the left hand **Navigation** sidebar to get around, or see the **Table of Contents** below (above). -The team would suggest taking a look at the **Introduction** chapters first. +The team recommends that newcomers to Ocelot's world start with the **Introduction** chapters. +For seasoned fans of Ocelot with a Production environment, it is advised to always consult the **Release Notes** in the **Welcome** section before upgrading the app to the latest `23.3`_ version. All **Features** are listed in alphabetical order. The primary features include :doc:`../features/configuration` and :doc:`../features/routing`. @@ -27,6 +28,7 @@ We adhere to a development process outlined in :doc:`../building/releaseprocess` :caption: Welcome releasenotes + introduction/contributing .. toctree:: :maxdepth: 3 @@ -34,7 +36,6 @@ We adhere to a development process outlined in :doc:`../building/releaseprocess` introduction/bigpicture introduction/gettingstarted - introduction/contributing introduction/notsupported introduction/gotchas diff --git a/docs/introduction/contributing.rst b/docs/introduction/contributing.rst index a11f7d1c1..41af425a8 100644 --- a/docs/introduction/contributing.rst +++ b/docs/introduction/contributing.rst @@ -1,8 +1,8 @@ Contributing ============ -Pull requests, issues and commentary welcome! +`Pull requests `_, `issues `_, and commentary are welcome at the `Ocelot GitHub repository `_. -Ideas, questions could be posted to Ocelot `Discussions `_ space. +For `ideas `_ and `questions `_, please post them in the `Ocelot Discussions `_ space. -We do follow development process which is described in :doc:`../building/releaseprocess`. +Our development process is detailed in the :doc:`../building/releaseprocess` documentation. diff --git a/docs/releasenotes.rst b/docs/releasenotes.rst index e64bcab58..ef74dac15 100644 --- a/docs/releasenotes.rst +++ b/docs/releasenotes.rst @@ -51,37 +51,34 @@ Welcome ####### -Abc... +Welcome to the Ocelot `23.3`_ documentation! +It is recommended to read all :ref:`release-notes` if you have deployed the Ocelot app in a production environment and are planning to upgrade to major or patched versions. -.. .. admonition:: Patches +The major version `23.3.0`_ includes several patches, the history of which is provided below. -Patches -------- +.. admonition:: Patches -- `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. -- `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release. - Codename decoding links + - `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. + - `23.3.4`_, on Oct 3, 2024. Hot fixing version `23.3.0`_, codenamed `Blue Olympic Balumbes `_ release, + with codename decoding links: - - **for men** :htm:`→` naked `Blue Olympic Fiend `_ - - **for women** :htm:`→` not a well-dressed woman sings at the opening ceremony, so "Not `Celine Dion `_" - - **for black men** :htm:`→` don't care about White movements, so enjoy `Black Men's Basketball Final `_ in `Paris 2024 `_: - be proud of Stephen Curry, "just give me a ball" boy, as an absolute rockstar, made `shot 1 `_, `shot 2 `_, `shot 3 `_ and final `shot 4 `_. + - **for men**: naked `Blue Olympic Fiend `_ + - **for women**: `not a well-dressed woman `_ sings at the opening ceremony, so "Not `Celine Dion `_" + - **for black men**: enjoy `Men's Basketball Final `_ in `Paris 2024 `_. + Be proud of Stephen Curry, "just give me a ball" boy, as an absolute rockstar, made `shot 1 `_, `shot 2 `_, `shot 3 `_ and final `shot 4 `_. -- `23.3.5`_, on Oct 11, 2024. Documentation patch: Html and Pdf doc layouts. + - `23.3.5`_, on Oct 12, 2024. Documentation patch: Html and Pdf doc layouts. + +.. _release-notes: Release Notes ------------- | Release Tag: `23.3.0`_ -| Release Codename: `Twilight Texas `_ - - :htm:`
Codename decoding links` - - - `for men `_ - - `for women `_ - - `for black men `_ - - :htm:`
` +| Release Codename: `Twilight Texas `_, with codename decoding links: + `for men `_, + `for women `_, + `for black men `_. What's new? ^^^^^^^^^^^ @@ -96,10 +93,7 @@ What's new? - 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`_ + | For further details, refer to the respective pull requests for both providers: ``Kube`` (PR `2052`_), ``Consul`` (PR `2067`_). - :doc:`../features/routing`: Introducing the new ":ref:`routing-upstream-headers`" feature by `@jlukawska`_. From f860c9304cb4c21b88e954311c98afb9d70502d0 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Sat, 12 Oct 2024 14:58:19 +0300 Subject: [PATCH 10/13] patch 10 --- docs/index.rst | 3 +-- docs/introduction/contributing.rst | 8 -------- docs/releasenotes.rst | 10 ++++++++++ 3 files changed, 11 insertions(+), 10 deletions(-) delete mode 100644 docs/introduction/contributing.rst diff --git a/docs/index.rst b/docs/index.rst index b9d17c402..65ba8afc7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,7 +13,7 @@ Thanks for taking a look at the Ocelot documentation! Please use the left hand **Navigation** sidebar to get around, or see the **Table of Contents** below (above). The team recommends that newcomers to Ocelot's world start with the **Introduction** chapters. -For seasoned fans of Ocelot with a Production environment, it is advised to always consult the **Release Notes** in the **Welcome** section before upgrading the app to the latest `23.3`_ version. +For seasoned fans of Ocelot with a Production environment, it is advised to always consult the :ref:`release-notes` in the **Welcome** section before upgrading the app to the latest `23.3`_ version. All **Features** are listed in alphabetical order. The primary features include :doc:`../features/configuration` and :doc:`../features/routing`. @@ -28,7 +28,6 @@ We adhere to a development process outlined in :doc:`../building/releaseprocess` :caption: Welcome releasenotes - introduction/contributing .. toctree:: :maxdepth: 3 diff --git a/docs/introduction/contributing.rst b/docs/introduction/contributing.rst deleted file mode 100644 index 41af425a8..000000000 --- a/docs/introduction/contributing.rst +++ /dev/null @@ -1,8 +0,0 @@ -Contributing -============ - -`Pull requests `_, `issues `_, and commentary are welcome at the `Ocelot GitHub repository `_. - -For `ideas `_ and `questions `_, please post them in the `Ocelot Discussions `_ space. - -Our development process is detailed in the :doc:`../building/releaseprocess` documentation. diff --git a/docs/releasenotes.rst b/docs/releasenotes.rst index ef74dac15..03a3e2583 100644 --- a/docs/releasenotes.rst +++ b/docs/releasenotes.rst @@ -52,6 +52,7 @@ Welcome ####### Welcome to the Ocelot `23.3`_ documentation! + It is recommended to read all :ref:`release-notes` if you have deployed the Ocelot app in a production environment and are planning to upgrade to major or patched versions. The major version `23.3.0`_ includes several patches, the history of which is provided below. @@ -170,3 +171,12 @@ Documentation Summary - :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 + +Contributing +------------ + +`Pull requests `_, `issues `_, and commentary are welcome at the `Ocelot GitHub repository `_. + +For `ideas `_ and `questions `_, please post them in the `Ocelot Discussions `_ space. + +Our development process is detailed in the :doc:`../building/releaseprocess` documentation. From b1aaba0067dd27024647061688ec5c5b3816c562 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Sat, 12 Oct 2024 19:28:05 +0300 Subject: [PATCH 11/13] #2160 #2164 Update Rate Limiting doc: explain global configuration --- docs/features/ratelimiting.rst | 62 +++++++++++++++++++++++----------- 1 file changed, 43 insertions(+), 19 deletions(-) diff --git a/docs/features/ratelimiting.rst b/docs/features/ratelimiting.rst index 94db1db5d..6f15933be 100644 --- a/docs/features/ratelimiting.rst +++ b/docs/features/ratelimiting.rst @@ -27,23 +27,25 @@ To implement *rate limiting* for a Route, you need to incorporate the following "Limit": 1 } -* **ClientWhitelist** - An array containing the whitelisted clients. Clients listed here will be exempt from rate limiting. - For more information on the **ClientIdHeader** option, refer to the :ref:`rl-global-configuration` section. -* **EnableRateLimiting** - This setting enables rate limiting on endpoints. -* **Period** - This parameter defines the duration for which the limit is applicable, such as ``1s`` (seconds), ``5m`` (minutes), ``1h`` (hours), and ``1d`` (days). - If you reach the exact **Limit** of requests, the excess occurs immediately, and the **PeriodTimespan** begins. - You must wait for the **PeriodTimespan** duration to pass before making another request. - Should you exceed the number of requests within the period more than the **Limit** permits, the **QuotaExceededMessage** will appear in the response, accompanied by the **HttpStatusCode**. -* **PeriodTimespan** - This parameter indicates the time in **seconds** after which a retry is permissible. - During this interval, the **QuotaExceededMessage** will appear in the response, accompanied by an **HttpStatusCode**. +* ``ClientWhitelist``: An array containing the whitelisted clients. Clients listed here will be exempt from rate limiting. + For more information on the ``ClientIdHeader`` option, refer to the :ref:`rl-global-configuration` section. +* ``EnableRateLimiting``: This setting enables rate limiting on endpoints. +* ``Period``: This parameter defines the duration for which the limit is applicable, such as ``1s`` (seconds), ``5m`` (minutes), ``1h`` (hours), and ``1d`` (days). + If you reach the exact ``Limit`` of requests, the excess occurs immediately, and the ``PeriodTimespan`` begins. + You must wait for the ``PeriodTimespan`` duration to pass before making another request. + Should you exceed the number of requests within the period more than the ``Limit`` permits, the ``QuotaExceededMessage`` will appear in the response, accompanied by the ``HttpStatusCode``. +* ``PeriodTimespan``: This parameter indicates the time in **seconds** after which a retry is permissible. + During this interval, the ``QuotaExceededMessage`` will appear in the response, accompanied by an ``HttpStatusCode``. Clients are advised to consult the ``Retry-After`` header to determine the timing of subsequent requests. -* **Limit** - This parameter defines the upper limit of requests a client is allowed to make within a specified **Period**. +* ``Limit``: This parameter defines the upper limit of requests a client is allowed to make within a specified ``Period``. .. _rl-global-configuration: Global Configuration ^^^^^^^^^^^^^^^^^^^^ + Global options are only accessible in the special :ref:`routing-dynamic` mode. + You can set the following in the ``GlobalConfiguration`` section of `ocelot.json`_: .. code-block:: json @@ -58,26 +60,48 @@ You can set the following in the ``GlobalConfiguration`` section of `ocelot.json } } -* **DisableRateLimitHeaders** - Determines if the ``X-Rate-Limit`` and ``Retry-After`` headers are disabled. -* **QuotaExceededMessage** - Defines the message displayed when the quota is exceeded. It is optional and the default message is informative. -* **HttpStatusCode** - Indicates the HTTP status code returned during *rate limiting*. The default value is **429** (`Too Many Requests`_). -* **ClientIdHeader** - Specifies the header used to identify clients, with ``ClientId`` as the default. -Future and ASP.NET Core Implementation --------------------------------------- +.. list-table:: + :widths: 35 65 + + * - *Property* + - *Description* + * - ``DisableRateLimitHeaders`` + - Determines if the ``X-Rate-Limit`` and ``Retry-After`` headers are disabled + * - ``QuotaExceededMessage`` + - Defines the message displayed when the quota is exceeded. It is optional and the default message is informative. + * - ``HttpStatusCode`` + - Indicates the HTTP status code returned during *rate limiting*. The default value is **429** (`Too Many Requests`_). + * - ``ClientIdHeader`` + - Specifies the header used to identify clients, with ``ClientId`` as the default. + +Notes +""""" + +1. Global ``RateLimitOptions`` are supported when the :ref:`sd-dynamic-routing` feature is configured with :doc:`../features/servicediscovery`. + Hence, if :doc:`../features/servicediscovery` is not set up, only the options for static routes need to be defined to impose limitations at the route level. +2. Global *Rate Limiting* options may not be practical because they impose limits on all routes. + It's reasonable to assert that in a Microservices architecture, it's an unusual approach to apply the same limitations to all routes. + Configuring per-route limiting could be a more tailored solution. + Global *Rate Limiting* is logical if all routes share the same downstream hosts, thus limiting the usage of a single service. +3. *Rate Limiting* is now built-in with ASP.NET Core 7, as discussed in the following topic below. + Our team holds the view that the ASP.NET ``RateLimiter`` enables global limitations through its rate limiting policies. + +Future and ASP.NET Implementation +--------------------------------- The Ocelot team is contemplating a redesign of the *Rate Limiting* feature following the `Announcing Rate Limiting for .NET`_ by Brennan Conroy on July 13th, 2022. Currently, no decision has been made, and the previous version of the feature remains part of the `20.0`_ release for .NET 7. [#f2]_ -Discover the new features being introduced in the ASP.NET Core 7.0 release: +Discover the new features in the ASP.NET Core 7.0 release: * The `RateLimiter Class `_, available since ASP.NET Core 7.0 * The `System.Threading.RateLimiting `_ NuGet package * The `Rate limiting middleware in ASP.NET Core `_ article by Arvin Kahbazi, Maarten Balliauw, and Rick Anderson -While retaining the old implementation as an Ocelot built-in feature makes sense, we plan to transition to the new Rate Limiter from the ``Microsoft.AspNetCore.RateLimiting`` namespace. +While it makes sense to retain the old implementation as a built-in feature of Ocelot, we are planning to transition to the new Rate Limiter from the ``Microsoft.AspNetCore.RateLimiting`` namespace. -Please share your thoughts with us in the `Discussions `_ space of the repository. |octocat| +We invite you to share your thoughts with us in the `Discussions `_ space of the repository. |octocat| """" From b78ec97e244eb7b3da24fdff87ee0db4f3a03482 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Sat, 12 Oct 2024 19:38:42 +0300 Subject: [PATCH 12/13] Fix table header --- docs/features/ratelimiting.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/features/ratelimiting.rst b/docs/features/ratelimiting.rst index 6f15933be..89127ae9e 100644 --- a/docs/features/ratelimiting.rst +++ b/docs/features/ratelimiting.rst @@ -63,6 +63,7 @@ You can set the following in the ``GlobalConfiguration`` section of `ocelot.json .. list-table:: :widths: 35 65 + :header-rows: 1 * - *Property* - *Description* From a0363760e6757922d73bcfc7f2b2cc07e4b22ea7 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Sat, 12 Oct 2024 21:06:22 +0300 Subject: [PATCH 13/13] Prepare technical release --- ReleaseNotes.md | 35 ++++++----------------------------- build.cake | 30 ++++++++++++++++++++---------- 2 files changed, 26 insertions(+), 39 deletions(-) diff --git a/ReleaseNotes.md b/ReleaseNotes.md index 4a6e9ebdc..431faf471 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -1,31 +1,8 @@ -## đŸ”Ĩ Hot fixing v[23.3](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0) (version {0}) aka [Blue Olympic Balumbes](https://www.youtube.com/live/j-Ou-ggS718?si=fPPwmOwjYEZq70H9&t=9518) release -> Codenamed: **[Blue Olympic Fiend](https://www.youtube.com/live/j-Ou-ggS718?si=fPPwmOwjYEZq70H9&t=9518)** +## :package: Documentation patch (version {0}), technical release > Read the Docs: [Ocelot 23.3](https://ocelot.readthedocs.io/en/{0}/) -> Hot fixed versions: [23.3.0](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0), [23.3.3](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.3) -> Milestone: [v23.3 Hotfixes](https://github.com/ThreeMammals/Ocelot/milestone/8) +> PDF Doc: [Ocelot 23.3](https://ocelot.readthedocs.io/_/downloads/en/{0}/pdf/) +> Hot fixed version: [23.3.4](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4) -❤ī¸ A heartfelt "Thank You" to [Roman Shevchik](https://github.com/antikorol) and [Massimiliano Innocenti](https://github.com/minnocenti901) for their contributions in testing and reporting the [Service Discovery](https://github.com/ThreeMammals/Ocelot/labels/Service%20Discovery) issues, #2110 and #2119, respectively! - -### ℹī¸ About -This release delivers a number of bug fixes for the predecessor's [23.3.0](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0) release, which is full of new features but was not tested well. All bugs were combined into the [v23.3 Hotfixes](https://github.com/ThreeMammals/Ocelot/milestone/8) milestone. - -Following the substantial refactoring of [Service Discovery](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/servicediscovery.rst) providers in the [23.3.0](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0) release, the community identified and we have acknowledged several [critical service discovery defects](https://github.com/ThreeMammals/Ocelot/issues?q=is%3Aissue+milestone%3A%22v23.3+Hotfixes%22+label%3A%22Service+Discovery%22) with providers such as [Kube](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/kubernetes.rst) and [Consul](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/servicediscovery.rst#consul). The `Kube` provider, while somewhat unstable, remained operational; however, the `Consul` provider was entirely non-functional. - -📓 If your projects rely on the [Service Discovery](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html) feature and cannot function without it, please upgrade to this version to utilize the full list of features of version [23.3.0](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0). - -### 🧑‍đŸ’ģ Technical Information -A comprehensive explanation of the technical details would span several pages; therefore, it is advisable for fans of Ocelot to review all pertinent technical information within the issue descriptions associated with [the milestone](https://github.com/ThreeMammals/Ocelot/milestone/8). -Our team has implemented some **Breaking Changes** which we urge you to review carefully (details follow). - -### ⚠ī¸ Breaking Changes -Listed by priority: -- `ILoadBalancer` interface alteration: Method `Lease` is now `LeaseAsync`. - Interface FQN: `Ocelot.LoadBalancer.LoadBalancers.ILoadBalancer` - Method FQN: `Ocelot.LoadBalancer.LoadBalancers.ILoadBalancer.LeaseAsync` -- `DefaultConsulServiceBuilder` constructor modification: The first parameter's type has been changed from `Func` to `IHttpContextAccessor`. - Class FQN: `Ocelot.Provider.Consul.DefaultConsulServiceBuilder` - Constructor signature: `public DefaultConsulServiceBuilder(IHttpContextAccessor contextAccessor, IConsulClientFactory clientFactory, IOcelotLoggerFactory loggerFactory)` -- Adjustments to `Lease` type: The `Lease` has been restructured from a class to a structure and elevated in the namespace hierarchy. - Struct FQN: `Ocelot.LoadBalancer.Lease` - -📓 Should your [custom solutions](https://ocelot.readthedocs.io/en/latest/search.html?q=custom) involve overriding default Ocelot classes and their behavior, redevelopment or at least recompilation of the solution, followed by deployment, will be necessary. +### :information_source: About +This documentation patch pertains to HTML and PDF document layouts. +No NuGet packages have been uploaded. diff --git a/build.cake b/build.cake index e72e7425d..d288d3efb 100644 --- a/build.cake +++ b/build.cake @@ -14,6 +14,9 @@ using System.Linq; using System.Text.RegularExpressions; const string Release = "Release"; // task name, target, and Release config name +const string AllFrameworks = "net6.0;net7.0;net8.0"; +const string LatestFramework = "net8.0"; + var compileConfig = Argument("configuration", Release); // compile // build artifacts @@ -47,7 +50,7 @@ var releaseNotes = new List(); // internal build variables - don't change these. string committedVersion = "0.0.0-dev"; GitVersion versioning = null; -bool IsTechnicalRelease = false; +bool IsTechnicalRelease = true; var target = Argument("target", "Default"); var slnFile = (target == Release) ? $"./Ocelot.{Release}.sln" : "./Ocelot.sln"; @@ -93,9 +96,10 @@ Task("Compile") }; if (target != Release) { - settings.Framework = "net8.0"; // build using .NET 8 SDK only + settings.Framework = LatestFramework; // build using .NET 8 SDK only } - Information($"Settings {nameof(DotNetBuildSettings.Framework)}: {settings.Framework}"); + string frameworkInfo = string.IsNullOrEmpty(settings.Framework) ? AllFrameworks : settings.Framework; + Information($"Settings {nameof(DotNetBuildSettings.Framework)}: {frameworkInfo}"); Information($"Settings {nameof(DotNetBuildSettings.Configuration)}: {settings.Configuration}"); DotNetBuild(slnFile, settings); }); @@ -344,7 +348,7 @@ Task("RunUnitTests") .IsDependentOn("Compile") .Does(() => { - var testSettings = new DotNetTestSettings + var settings = new DotNetTestSettings { Configuration = compileConfig, ResultsDirectory = artifactsForUnitTestsDir, @@ -357,10 +361,12 @@ Task("RunUnitTests") }; if (target != Release) { - testSettings.Framework = "net8.0"; // .NET 8 SDK only + settings.Framework = LatestFramework; // .NET 8 SDK only } + string frameworkInfo = string.IsNullOrEmpty(settings.Framework) ? AllFrameworks : settings.Framework; + Information($"Settings {nameof(DotNetTestSettings.Framework)}: {frameworkInfo}"); EnsureDirectoryExists(artifactsForUnitTestsDir); - DotNetTest(unitTestAssemblies, testSettings); + DotNetTest(unitTestAssemblies, settings); var coverageSummaryFile = GetSubDirectories(artifactsForUnitTestsDir) .First() @@ -408,15 +414,17 @@ Task("RunAcceptanceTests") var settings = new DotNetTestSettings { Configuration = compileConfig, - Framework = "net8.0", // .NET 8 SDK only + // Framework = LatestFramework, // .NET 8 SDK only ArgumentCustomization = args => args .Append("--no-restore") .Append("--no-build") }; if (target != Release) { - settings.Framework = "net8.0"; // .NET 8 SDK only + settings.Framework = LatestFramework; // .NET 8 SDK only } + string frameworkInfo = string.IsNullOrEmpty(settings.Framework) ? AllFrameworks : settings.Framework; + Information($"Settings {nameof(DotNetTestSettings.Framework)}: {frameworkInfo}"); EnsureDirectoryExists(artifactsForAcceptanceTestsDir); DotNetTest(acceptanceTestAssemblies, settings); }); @@ -428,15 +436,17 @@ Task("RunIntegrationTests") var settings = new DotNetTestSettings { Configuration = compileConfig, - Framework = "net8.0", // .NET 8 SDK only + // Framework = LatestFramework, // .NET 8 SDK only ArgumentCustomization = args => args .Append("--no-restore") .Append("--no-build") }; if (target != Release) { - settings.Framework = "net8.0"; // .NET 8 SDK only + settings.Framework = LatestFramework; // .NET 8 SDK only } + string frameworkInfo = string.IsNullOrEmpty(settings.Framework) ? AllFrameworks : settings.Framework; + Information($"Settings {nameof(DotNetTestSettings.Framework)}: {frameworkInfo}"); EnsureDirectoryExists(artifactsForIntegrationTestsDir); DotNetTest(integrationTestAssemblies, settings); });