From 414f63439d32ed9a3c09a77c86f035ed9c34aa56 Mon Sep 17 00:00:00 2001 From: Raman Maksimchuk Date: Sat, 12 Oct 2024 21:24:26 +0300 Subject: [PATCH] Release 23.3.5 | Documentation patch for HTML and PDF document layouts | +semver: patch (#2172) * index.rst patch * index.rst patch 2 * patch 3 * patch 4 * patch 5 * patch 6 * patch 7 * patch 8 * patch 9 * patch 10 * #2160 #2164 Update Rate Limiting doc: explain global configuration * Fix table header * Prepare technical release --- ReleaseNotes.md | 35 +--- build.cake | 30 ++- docs/conf.py | 9 +- docs/features/ratelimiting.rst | 63 ++++-- docs/index.rst | 302 +++++++---------------------- docs/introduction/contributing.rst | 8 - docs/releasenotes.rst | 182 +++++++++++++++++ 7 files changed, 330 insertions(+), 299 deletions(-) delete mode 100644 docs/introduction/contributing.rst create mode 100644 docs/releasenotes.rst 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); }); diff --git a/docs/conf.py b/docs/conf.py index 2c31a6b98..1cfc5e4a3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,15 +6,16 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'Ocelot' -copyright = ' 2016-2024 ThreeMammals Ocelot team' -author = 'Tom Pallister, Raman Maksimchuk and Ocelot Core team at ThreeMammals' +project = 'Ocelot Gateway' +copyright = ' 2016-2024, 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 = [ +] templates_path = ['_templates'] exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] diff --git a/docs/features/ratelimiting.rst b/docs/features/ratelimiting.rst index 94db1db5d..89127ae9e 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,49 @@ 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 + :header-rows: 1 + + * - *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| """" diff --git a/docs/index.rst b/docs/index.rst index 562646151..65ba8afc7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,236 +1,80 @@ -.. _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.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 -.. _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. - -All **Features** are arranged in alphabetical order. -The main features are :doc:`../features/configuration` and :doc:`../features/routing`. - -We **do** follow development process which is described 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:`
` - -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. - -Focus On -^^^^^^^^ - -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 - - -.. toctree:: - :maxdepth: 2 - :hidden: - :caption: Introduction - - introduction/bigpicture - introduction/gettingstarted - introduction/contributing - introduction/notsupported - introduction/gotchas - -.. toctree:: - :maxdepth: 2 - :hidden: - :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:: - :maxdepth: 2 - :hidden: - :caption: Building Ocelot +############################ +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 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 :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`. + +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:: Table of Contents + + .. toctree:: + :maxdepth: 2 + :caption: Welcome + + releasenotes + + .. toctree:: + :maxdepth: 3 + :caption: Introduction + + introduction/bigpicture + introduction/gettingstarted + introduction/notsupported + introduction/gotchas + + .. toctree:: + :maxdepth: 3 + :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:: + :maxdepth: 3 + :caption: Building Ocelot + + building/overview + building/building + building/tests + building/releaseprocess - building/overview - building/building - building/tests - building/releaseprocess diff --git a/docs/introduction/contributing.rst b/docs/introduction/contributing.rst deleted file mode 100644 index a11f7d1c1..000000000 --- a/docs/introduction/contributing.rst +++ /dev/null @@ -1,8 +0,0 @@ -Contributing -============ - -Pull requests, issues and commentary welcome! - -Ideas, questions could be posted to Ocelot `Discussions `_ space. - -We do follow development process which is described in :doc:`../building/releaseprocess`. diff --git a/docs/releasenotes.rst b/docs/releasenotes.rst new file mode 100644 index 000000000..03a3e2583 --- /dev/null +++ b/docs/releasenotes.rst @@ -0,0 +1,182 @@ +.. _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.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 +.. _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: + +####### +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. + +.. 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, + with codename decoding links: + + - **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 12, 2024. Documentation patch: Html and Pdf doc layouts. + +.. _release-notes: + +Release Notes +------------- + +| Release Tag: `23.3.0`_ +| Release Codename: `Twilight Texas `_, with codename decoding links: + `for men `_, + `for women `_, + `for black men `_. + +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`` (PR `2052`_), ``Consul`` (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 + +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.