diff --git a/ReleaseNotes.md b/ReleaseNotes.md index 725946f5c..1042ff4de 100644 --- a/ReleaseNotes.md +++ b/ReleaseNotes.md @@ -1,26 +1,32 @@ -## :fire: Hot fixing v[23.3.4](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4) (version {0}) aka [October'24](https://github.com/ThreeMammals/Ocelot/milestone/7) release -> Read the Docs: [Ocelot 23.3](https://ocelot.readthedocs.io/en/{0}/) -> Hot fixed version: [23.3.4](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4) -> Milestone: [October'24](https://github.com/ThreeMammals/Ocelot/milestone/7) - -:heart: A heartfelt "Thank You" to **[Nikolai Masson](https://github.com/Niksson)** (@Niksson) and **[Nikolay Kuksov](https://github.com/kick2nick)** (@kick2nick) for their contributions! +## :twisted_rightwards_arrows: Routing Update (version {0}) aka [MGGA](https://github.com/ThreeMammals/Ocelot/commits?author=ggnaegi) release +> Codenamed: **[Make Guillaume Great Again!](https://github.com/ThreeMammals/Ocelot/commits?author=ggnaegi)** +> Read the Docs: [Ocelot {0}](https://ocelot.readthedocs.io/en/{0}/) ### :information_source: About -This release provides minor bug fixes from the previous [23.3.4](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4) release. All bugs have been addressed in the [October'24](https://github.com/ThreeMammals/Ocelot/milestone/7) milestone. +This minor release significantly upgrades the [Routing](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/routing.rst) feature by supporting [embedded placeholders](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/routing.rst#embedded-placeholders-1) within path segments (between slashes). Additionally, the team has focused on enhancing the performance of `Regex` objects. + +### :new: What's new? +- **[Routing](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/routing.rst)**: Introducing the new "[Embedded Placeholders](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/routing.rst#embedded-placeholders-1)" feature by @ggnaegi. + As of November 2024, Ocelot was unable to process multiple [placeholders](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/routing.rst#placeholders) embedded between two forward slashes. It was also challenging to differentiate the placeholder from other elements within the slashes. For example, `/{{url}}-2/` for `/y-2/` would yield `{{url}} = y-2`. We are excited to introduce an enhanced method for evaluating placeholders that allows for the resolution of [placeholders](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/routing.rst#placeholders) within complex URLs. + For additional information, refer to PR #2200. -:notebook: For projects utilizing the [Service Discovery](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html) feature, it is recommended to update to this version to benefit from the unstable release [23.3.4](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4), which includes fixes for both `Consul` and `Kube` discovery providers. +### :up: Focus On +
+ Features: Routing, Core, Rate Limiting, Middleware Injection -### :technologist: Technical Information -The Ocelot solution encountered a significant issue with the disabled scope validation of services in the DI-container, affecting both testing projects and the core library. Initially, this was not problematic when services were designed as singletons by previous contributors and our team. However, with the introduction of more scoped services by the Ocelot team, it became clear that our testing projects could not adequately handle them. -This patch introduces scope validation across all domains: unit tests, acceptance tests, and the core library itself. We advise always enabling scope validation in your custom Ocelot solutions, especially when dealing with numerous C# overridden classes in the DI-container and any attached custom functionality. + - [Routing](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/routing.rst): The new feature is "[Embedded Placeholders](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/routing.rst#embedded-placeholders-1)" by @ggnaegi. + - [Core](https://github.com/ThreeMammals/Ocelot/labels/Core): All `Regex` logic has been refactored by @EngRajabi. + The Ocelot Core now boasts improved performance of `Regex` objects, striving to adhere to the [Best Practices for Regular Expressions in .NET](https://docs.microsoft.com/en-us/dotnet/standard/base-types/best-practices). It is estimated that each request could save from 1 to over 10 microseconds in processing time (though no benchmarks have been developed to measure this). + - [Rate Limiting](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/ratelimiting.rst): The persistent issue with [Rate Limiting headers](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/ratelimiting.rst#global-configuration:~:text=headers) has been resolved by @jlukawska. + The problem was the absence of unofficial `X-Rate-Limit-*` headers (found in the [RateLimitingHeaders](https://github.com/ThreeMammals/Ocelot/blob/{0}/src/Ocelot/RateLimiting/RateLimitingHeaders.cs) class) in the `RateLimitingMiddleware`'s response. For more details, see PR #1307. + Note that these unofficial headers have not yet been documented, so they may be subject to change since [Ocelot's RateLimiting headers do not align with industry standards, see links](https://github.com/ThreeMammals/Ocelot/blob/27d3df2d0fdfbf5acde12d9442dfc08836e8b982/src/Ocelot/RateLimiting/RateLimitingHeaders.cs#L6). + - [Middleware Injection](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/middlewareinjection.rst): The `OcelotPipelineConfiguration.ClaimsToHeadersMiddleware` property has been introduced by @kesskalli. + This new property enables the overriding of the [ClaimsToHeadersMiddleware](https://github.com/ThreeMammals/Ocelot/blob/{0}/docs/features/middlewareinjection.rst#middleware-injection:~:text=ClaimsToHeadersMiddleware). For additional information, refer to PR #1403. +
-The patch enhances functionality for two primary [Service Discovery](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/servicediscovery.rst) providers: -- The [Ocelot.Provider.Consul](https://www.nuget.org/packages/Ocelot.Provider.Consul) provider. The addressed bug is issue #2178, reported on October 17, 2024. - The `System.InvalidOperationException` error stating _"Cannot resolve scoped service 'Ocelot.Provider.Consul.Interfaces.IConsulServiceBuilder' from root provider"_ has been resolved. - To clarify, the `IConsulServiceBuilder` service is a scoped service in DI, injected via the `AddConsul()` or [AddConsul<T>()](https://github.com/ThreeMammals/Ocelot/blob/main/docs/features/servicediscovery.rst#addconsult-method) methods. Therefore, the `DefaultConsulServiceBuilder` should also be a scoped service, with `HttpContext` injected to meet your development requirements. -- The [Ocelot.Provider.Kubernetes](https://www.nuget.org/packages/Ocelot.Provider.Kubernetes) provider had an issue reported as #977 on August 1, 2019. - It involved a `System.InvalidOperationException` with the message: _"Cannot resolve scoped service 'KubeClient.IKubeApiClient' from root provider."_ This "invalid scopes" error occurred only in development mode, as release mode DLLs do not validate scopes. However, the `KubeApiClient` is designed to have a [scoped](https://github.com/tintoy/dotnet-kube-client/blob/84b055c885a2afe00781559ea400c0bd8cdfce6d/src/KubeClient.Extensions.DependencyInjection/ClientRegistrationExtensions.cs#L42-L43) lifetime. Acceptance tests passed because scope validation was disabled, and the `KubeClient` was [replaced](https://github.com/ThreeMammals/Ocelot/blob/414f63439d32ed9a3c09a77c86f035ed9c34aa56/test/Ocelot.AcceptanceTests/ServiceDiscovery/KubernetesServiceDiscoveryTests.cs#L315) with a singleton. This inconsistency was identified and reproduced by the old [977 issue](https://github.com/ThreeMammals/Ocelot/issues/977). As a temporary solution, the `IKubeApiClient` was [registered as a singleton](https://github.com/ThreeMammals/Ocelot/blob/e4bc9ff59d9defc385996a09be85fbb845e06af9/src/Ocelot.Provider.Kubernetes/OcelotBuilderExtensions.cs#L16). - Looking ahead, our team intends to redesign the Kubernetes provider to have a default service builder that is scoped, similar to the Consul provider. +
+ Documentation for v{0} -### :exclamation: Breaking Changes -Upgrading from [23.3.4](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4) to [{0}](https://github.com/ThreeMammals/Ocelot/releases/tag/{0}) introduces **no breaking changes**. However, upgrading from [23.3.0](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0) or earlier versions may result in some incompatibilities. For further information, please refer to the release notes of v[23.3.4](https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.4). + - [Routing](https://ocelot.readthedocs.io/en/{0}/features/routing.html): Introducing a new section on [Embedded Placeholders](https://ocelot.readthedocs.io/en/{0}/features/routing.html#embedded-placeholders) + - [Middleware Injection](https://ocelot.readthedocs.io/en/{0}/features/middlewareinjection.html): Documentation now includes the [ClaimsToHeadersMiddleware](https://ocelot.readthedocs.io/en/{0}/features/middlewareinjection.html#middleware-injection:~:text=ClaimsToHeadersMiddleware) feature +
diff --git a/build.cake b/build.cake index 6635f8693..71841a033 100644 --- a/build.cake +++ b/build.cake @@ -138,7 +138,6 @@ Task("Version") Task("GitLogUniqContributors") .Does(() => { - Information("---==< Unique Contributors >==---"); var command = "log --format=\"%aN|%aE\" "; // command += IsRunningOnCircleCI() ? "| sort | uniq" : // IsRunningInPowershell() ? "| Sort-Object -Unique" : "| sort | uniq"; @@ -159,7 +158,7 @@ Task("GitLogUniqContributors") Task("CreateReleaseNotes") .IsDependentOn("Version") - .IsDependentOn("GitLogUniqContributors") + //.IsDependentOn("GitLogUniqContributors") .Does(() => { Information($"Generating release notes at {releaseNotesFile}"); @@ -204,12 +203,14 @@ Task("CreateReleaseNotes") var emailInfo = debugUserEmail ? ", " + contributor.Email : string.Empty; return $"{stars} {contributor.Author}{emailInfo}"; } - // foreach (var contributor in summary) - // { - // starring.Add(CreateStars(contributor.Commits, contributor.Author)); - // } - // Information("---==< Old Starring >==---"); - // Information(string.Join(Environment.NewLine, starring)); + + Information("------==< Old Starring >==------"); + foreach (var contributor in summary) + { + starring.Add(CreateStars(contributor.Commits, contributor.Author)); + } + Information(string.Join(Environment.NewLine, starring)); + var commitsGrouping = summary .GroupBy(x => x.Commits) .Select(CreateCommitsGroupingItem) @@ -221,7 +222,7 @@ Task("CreateReleaseNotes") byFiles: (log, group, fGroup) => CreateStars(group.Commits, fGroup.Contributors.First().Contributor), byInsertions: (log, group, fGroup, insGroup) => CreateStars(group.Commits, insGroup.Contributors.First().Contributor), byDeletions: (log, group, fGroup, insGroup, contributor) => CreateStars(group.Commits, contributor.Contributor)); - Information("---==< Starring >==---"); + Information("------==< New Starring >==------"); Information(string.Join(Environment.NewLine, starring)); // Honoring aka Top Contributors @@ -366,15 +367,20 @@ Task("CreateReleaseNotes") } return log; } // END of IterateCommits - // releaseNotes.Add("### Honoring :medal_sports: aka Top Contributors :clap:"); - // releaseNotes.AddRange(topContributors.Take(3)); // Top 3 only, disabled 'breaker' logic - // releaseNotes.Add(""); + releaseNotes.Add("### Honoring :medal_sports: aka Top Contributors :clap:"); + releaseNotes.AddRange(topContributors.Take(3)); // Top 3 only, disabled 'breaker' logic + releaseNotes.Add(""); releaseNotes.Add("### Starring :star: aka Release Influencers :bowtie:"); releaseNotes.AddRange(starring); releaseNotes.Add(""); - // releaseNotes.Add($"### Features in Release {releaseVersion}"); - // var commitsHistory = GitHelper($"log --no-merges --date=format:\"%A, %B %d at %H:%M\" --pretty=format:\"%h by **%aN** on %ad →%n%s\" {lastRelease}..HEAD"); - // releaseNotes.AddRange(commitsHistory); + releaseNotes.Add($"### Features in Release {releaseVersion}"); + releaseNotes.Add(""); + releaseNotes.Add("
Logbook"); + releaseNotes.Add(""); + var commitsHistory = GitHelper($"log --no-merges --date=format:\"%A, %B %d at %H:%M\" --pretty=format:\"- %h by **%aN** on %ad →%n %s\" {lastRelease}..HEAD"); + releaseNotes.AddRange(commitsHistory); + releaseNotes.Add("
"); + releaseNotes.Add(""); WriteReleaseNotes(); }); diff --git a/docs/conf.py b/docs/conf.py index 1cfc5e4a3..fa8ee82c9 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,7 +9,7 @@ project = 'Ocelot Gateway' copyright = ' 2016-2024, ThreeMammals Ocelot team' author = 'Tom Pallister, Raman Maksimchuk' -release = '23.3' +release = '23.4' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration diff --git a/docs/features/routing.rst b/docs/features/routing.rst index ab624cba7..44135b775 100644 --- a/docs/features/routing.rst +++ b/docs/features/routing.rst @@ -76,15 +76,17 @@ This means that when Ocelot tries to match the incoming upstream URL with an ups Embedded Placeholders [#f1]_ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Until now (November 2024), Ocelot could not evaluate multiple placeholders embedded between two forward slashes. -Additionally, it was not possible to distinguish the placeholder from other elements between the slashes. -For instance, ``/{url}-2/`` for ``/y-2/`` would return ``{url} = y-2``. We now propose a revised version of placeholder evaluation that enables the resolution of placeholders in complex URLs, such as: +Prior to version `23.4`_, Ocelot was unable to evaluate multiple placeholders embedded between two forward slashes, ``/``. +It was also challenging to differentiate the placeholder from other elements within the slashes. +For example, ``/{url}-2/`` when applied to ``/y-2/`` would yield ``{url} = y-2``. -Path pattern: ``/api/invoices_{url0}/{url1}-{url2}_abcd/{url3}?urlId={url4}`` +We now introduce an improved method of placeholder evaluation that facilitates the identification of placeholders in complex URLs. For example: -Upstream path: ``/api/invoices_super/123-456_abcd/789?urlId=987`` +- **Given** path pattern: ``/api/invoices_{url0}/{url1}-{url2}_abcd/{url3}?urlId={url4}`` +- **When** upstream URL path: ``/api/invoices_super/123-456_abcd/789?urlId=987`` +- **Then** resulting placeholders would be ``{url0} = super``, ``{url1} = 123``, ``{url2} = 456``, ``{url3} = 789``, ``{url4} = 987`` -Parsed placeholders: ``{url0} = super``, ``{url1} = 123``, ``{url2} = 456``, ``{url3} = 789``, ``{url4} = 987`` + **Note**, we believe this feature should be compatible with any URL query strings, although it has not been thoroughly tested. .. _routing-empty-placeholders: @@ -419,16 +421,30 @@ The idea is to enable dynamic routing when using a :doc:`../features/servicedisc See the :ref:`sd-dynamic-routing` docs if this sounds interesting to you. -.. [#f1] ":ref:`routing-embedded-placeholders`" feature was requested as part of `issue 2199 `_. -.. [#f2] ":ref:`routing-empty-placeholders`" feature is available starting in version `23.0 `_, see issue `748 `_ and the `23.0 `__ release notes for details. -.. [#f3] ":ref:`routing-upstream-host`" feature was requested as part of `issue 216 `_. -.. [#f4] ":ref:`routing-upstream-headers`" feature was proposed in `issue 360 `_, and released in version `24.0 `_. -.. [#f5] ":ref:`routing-security-options`" feature was requested as part of `issue 628 `_ (of `12.0.1 `_ version), then redesigned and improved by `issue 1400 `_, and published in version `20.0 `_ docs. -.. [#f6] ":ref:`routing-dynamic`" feature was requested as part of `issue 340 `_. Complete reference: :ref:`sd-dynamic-routing`. +.. [#f1] ":ref:`routing-embedded-placeholders`" feature was requested as part of issue `2199`_ , and released in version `23.4`_ +.. [#f2] ":ref:`routing-empty-placeholders`" feature is available starting in version `23.0`_, see issue `748`_ and the `23.0`_ release notes for details. +.. [#f3] ":ref:`routing-upstream-host`" feature was requested as part of issue `216`_. +.. [#f4] ":ref:`routing-upstream-headers`" feature was proposed in issue `360`_, and released in version `23.3`_. +.. [#f5] ":ref:`routing-security-options`" feature was requested as part of issue `628`_ (version `12.0.1`_), then redesigned and improved by issue `1400`_, and published in version `20.0`_ docs. +.. [#f6] ":ref:`routing-dynamic`" feature was requested as part of issue `340`_. Refer to complete reference: :ref:`sd-dynamic-routing`. .. _model binding: https://learn.microsoft.com/en-us/aspnet/core/mvc/models/model-binding?view=aspnetcore-8.0#collections .. _Bind arrays and string values from headers and query strings: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/parameter-binding?view=aspnetcore-8.0#bind-arrays-and-string-values-from-headers-and-query-strings + +.. _216: https://github.com/ThreeMammals/Ocelot/issues/216 .. _270: https://github.com/ThreeMammals/Ocelot/issues/270 +.. _340: https://github.com/ThreeMammals/Ocelot/issues/340 +.. _360: https://github.com/ThreeMammals/Ocelot/issues/360 .. _473: https://github.com/ThreeMammals/Ocelot/issues/473 +.. _628: https://github.com/ThreeMammals/Ocelot/issues/628 +.. _748: https://github.com/ThreeMammals/Ocelot/issues/748 .. _952: https://github.com/ThreeMammals/Ocelot/issues/952 .. _1174: https://github.com/ThreeMammals/Ocelot/issues/1174 +.. _1400: https://github.com/ThreeMammals/Ocelot/issues/1400 +.. _2199: https://github.com/ThreeMammals/Ocelot/issues/2199 + +.. _12.0.1: https://github.com/ThreeMammals/Ocelot/releases/tag/12.0.1 +.. _20.0: https://github.com/ThreeMammals/Ocelot/releases/tag/20.0.0 +.. _23.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.0.0 +.. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0 +.. _23.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.0 diff --git a/docs/index.rst b/docs/index.rst index 645b9d704..ad4a843ab 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,19 +1,14 @@ -.. _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.6 +.. _23.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.0 ############################ -Ocelot `23.3`_ Documentation +Ocelot `23.4`_ 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. +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.4`_ version. All **Features** are listed in alphabetical order. The primary features include :doc:`../features/configuration` and :doc:`../features/routing`. diff --git a/docs/releasenotes.rst b/docs/releasenotes.rst index d6b828444..1070282d0 100644 --- a/docs/releasenotes.rst +++ b/docs/releasenotes.rst @@ -1,47 +1,16 @@ -.. _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 +.. _@ggnaegi: https://github.com/ggnaegi +.. _@EngRajabi: https://github.com/EngRajabi .. _@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.6: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.6 -.. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.6 - -.. _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 +.. _@kesskalli: https://github.com/kesskalli + +.. _23.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.0 +.. _23.4.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.0 + +.. _1111: https://github.com/ThreeMammals/Ocelot/issues/1111 +.. _1307: https://github.com/ThreeMammals/Ocelot/pull/1307 +.. _1403: https://github.com/ThreeMammals/Ocelot/pull/1403 +.. _2200: https://github.com/ThreeMammals/Ocelot/pull/2200 .. role:: htm(raw) :format: html @@ -52,134 +21,102 @@ Welcome ####### -Welcome to the Ocelot `23.3`_ documentation! +Welcome to the Ocelot `23.4`_ 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: +.. The major version `23.4.0`_ includes several patches, the history of which is provided below. - - **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 `_. +.. .. admonition:: Patches - - `23.3.5`_, on Oct 12, 2024. Documentation patch: Html and Pdf doc layouts. - - `23.3.6`_, on Oct 31, 2024. Version `23.3.4`_ patch: DI-scopes validation, :doc:`../features/servicediscovery` feature update. +.. - `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch. .. _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. +đŸ“ĸ Release Notes +----------------- - | 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`_). +| Release Tag: `23.4.0`_ +| Release Codename: `Make Guillaume Great Again! `_ -- :doc:`../features/routing`: Introducing the new ":ref:`routing-upstream-headers`" feature by `@jlukawska`_. + :htm:`
With codename decoding links:` - | 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`_. + - **for men**: The abbreviation "MGGA" is reminiscent of the `MAGA slogan `_ + - **for women**: Donald is fond of caps, particularly the `MAGA cap `_, and it's amusing to see children's reactions when `We Ask Kids How Mr.D is Doing `_? + - **for black men**: Here are some highlights of Donald's antics aka Mr. D: -- :doc:`../features/configuration`: Introducing the ":ref:`config-version-policy`" feature by `@ibnuda`_. + | 1 `Mr. D stops to retrieve Marine's hat `_ + | 2 `M-A-G-A caps take flight `_ + | 3 `Mr. D Dances To 'YMCA' `_ + | 4 `Elon is more than just a MAGAr `_ + | 5 `Mr. D looks for a job at McDonald's in 2024 `_ + | lastly, `Mr. D serves customers at McDonald's Drive-Thru `_ - 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. + :htm:`
` - | 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`_. +ℹī¸ About +^^^^^^^^^ -- :doc:`../features/configuration`: Introducing the new ":ref:`config-route-metadata`" feature by `@vantm`_. +This minor release significantly upgrades the :doc:`../features/routing` feature by supporting :ref:`routing-embedded-placeholders` within path segments (between slashes). +Additionally, the team has focused on enhancing the performance of ``Regex`` objects. - Undoubtedly, this is the standout feature of the release! ⭐ +🆕 What's New? +^^^^^^^^^^^^^^^ - Route metadata enables Ocelot developers to incorporate custom functions that address specific needs or to create their own plugins/extensions. +- :doc:`../features/routing`: Introducing the new ":ref:`routing-embedded-placeholders`" feature by `@ggnaegi`_. - 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. + | As of November 2024, Ocelot was unable to process multiple :ref:`routing-placeholders` embedded between two forward slashes (``/``). It was also challenging to differentiate the placeholder from other elements within the slashes. For example, ``/{url}-2/`` for ``/y-2/`` would yield ``{url} = y-2``. We are excited to introduce an enhanced method for evaluating placeholders that allows for the resolution of :ref:`routing-placeholders` within complex URLs. + | For additional information, refer to PR `2200`_. - | 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. +🆙 Feature Updates +^^^^^^^^^^^^^^^^^^^ -Updates of the features -^^^^^^^^^^^^^^^^^^^^^^^ +.. _Best Practices for Regular Expressions in .NET: https://docs.microsoft.com/en-us/dotnet/standard/base-types/best-practices +.. _RateLimitingHeaders: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/RateLimiting/RateLimitingHeaders.cs +.. _Ocelot's RateLimiting headers do not align with industry standards: https://github.com/ThreeMammals/Ocelot/blob/27d3df2d0fdfbf5acde12d9442dfc08836e8b982/src/Ocelot/RateLimiting/RateLimitingHeaders.cs#L6 +.. _ClaimsToHeadersMiddleware: https://ocelot.readthedocs.io/en/latest/search.html?q=ClaimsToHeadersMiddleware -- :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`_). +- :doc:`../features/routing`: The new feature is ":ref:`routing-embedded-placeholders`" by `@ggnaegi`_. - | 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. +- `Core `_: All ``Regex`` logic has been refactored by `@EngRajabi`_. -Ocelot extra packages -^^^^^^^^^^^^^^^^^^^^^ + The Ocelot Core now boasts improved performance of ``Regex`` objects, striving to adhere to the `Best Practices for Regular Expressions in .NET`_. + It is estimated that each request could save from 1 to over 10 microseconds in processing time (though **no** benchmarks have been developed to measure this). -- `Ocelot.Provider.Polly `_ +- :doc:`../features/ratelimiting`: The persistent issue with *Rate Limiting* headers has been resolved by `@jlukawska`_. - - 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`_. + | The problem was the absence of unofficial ``X-Rate-Limit-*`` headers (found in the `RateLimitingHeaders`_ class) in the ``RateLimitingMiddleware``'s response. + | For more details, see PR `1307`_. + | Note that these unofficial headers have not yet been documented, so they may be subject to change since `Ocelot's RateLimiting headers do not align with industry standards`_. -Stabilization (bug fixing) -^^^^^^^^^^^^^^^^^^^^^^^^^^ +- :doc:`../features/middlewareinjection`: The ``ClaimsToHeadersMiddleware`` property has been introduced by `@kesskalli`_. -- 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`_ + This new property of the ``OcelotPipelineConfiguration`` class enables the overriding of the `ClaimsToHeadersMiddleware`_. + For additional information, refer to PR `1403`_. -See `all bugs `_ of the `Spring'24 `_ milestone +📘 Documentation Summary +^^^^^^^^^^^^^^^^^^^^^^^^^ -Documentation Summary -^^^^^^^^^^^^^^^^^^^^^ +- :doc:`../features/routing`: New section on :ref:`routing-embedded-placeholders`. +- :doc:`../features/middlewareinjection`: Added the `ClaimsToHeadersMiddleware`_ property. -- :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 +------------------ -Contributing ------------- +.. |octocat| image:: https://github.githubassets.com/images/icons/emoji/octocat.png + :alt: octocat + :height: 30 + :target: https://github.com/ThreeMammals/Ocelot/ +.. _Pull requests: https://github.com/ThreeMammals/Ocelot/pulls +.. _issues: https://github.com/ThreeMammals/Ocelot/issues +.. _Ocelot GitHub: https://github.com/ThreeMammals/Ocelot/ +.. _Ocelot Discussions: https://github.com/ThreeMammals/Ocelot/discussions +.. _ideas: https://github.com/ThreeMammals/Ocelot/discussions/categories/ideas +.. _questions: https://github.com/ThreeMammals/Ocelot/discussions/categories/q-a -`Pull requests `_, `issues `_, and commentary are welcome at the `Ocelot GitHub repository `_. +`Pull requests`_, `issues`_, and commentary are welcome at the `Ocelot GitHub`_ repository. -For `ideas `_ and `questions `_, please post them in the `Ocelot Discussions `_ space. +For `ideas`_ and `questions`_, please post them in the `Ocelot Discussions`_ space. Our :doc:`../building/devprocess` is a part of successful :doc:`../building/releaseprocess`. If you are a new contributor, it is crucial to read :doc:`../building/devprocess` attentively to grasp our methods for efficient and swift feature delivery.