Skip to content

Release 23.4 | Routing Update | McDonald's release | +semver: minor #2206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 18, 2024
Merged

Release 23.4 | Routing Update | McDonald's release | +semver: minor #2206

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f2a1187
Update ReleaseNotes.md
raman-m Nov 18, 2024
1917dbe
Update docs
raman-m Nov 18, 2024
109b540
Update and test build script
raman-m Nov 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 26 additions & 20 deletions ReleaseNotes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<details>
<summary><b>Features</b>: Routing, Core, Rate Limiting, Middleware Injection</summary>

### :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.
</details>

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&lt;T&gt;()](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.
<details>
<summary><b>Documentation</b> for <a href="https://ocelot.readthedocs.io/en/{0}/">v{0}</a></summary>

### :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
</details>
36 changes: 21 additions & 15 deletions build.cake
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand All @@ -159,7 +158,7 @@ Task("GitLogUniqContributors")

Task("CreateReleaseNotes")
.IsDependentOn("Version")
.IsDependentOn("GitLogUniqContributors")
//.IsDependentOn("GitLogUniqContributors")
.Does(() =>
{
Information($"Generating release notes at {releaseNotesFile}");
Expand Down Expand Up @@ -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)
Expand All @@ -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
Expand Down Expand Up @@ -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:\"<sub>%h by **%aN** on %ad &rarr;</sub>%n%s\" {lastRelease}..HEAD");
// releaseNotes.AddRange(commitsHistory);
releaseNotes.Add($"### Features in Release {releaseVersion}");
releaseNotes.Add("");
releaseNotes.Add("<details><summary>Logbook</summary>");
releaseNotes.Add("");
var commitsHistory = GitHelper($"log --no-merges --date=format:\"%A, %B %d at %H:%M\" --pretty=format:\"- <sub>%h by **%aN** on %ad &rarr;</sub>%n %s\" {lastRelease}..HEAD");
releaseNotes.AddRange(commitsHistory);
releaseNotes.Add("</details>");
releaseNotes.Add("");
WriteReleaseNotes();
});

Expand Down
2 changes: 1 addition & 1 deletion docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
40 changes: 28 additions & 12 deletions docs/features/routing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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 <https://github.com/ThreeMammals/Ocelot/issues/2199>`_.
.. [#f2] ":ref:`routing-empty-placeholders`" feature is available starting in version `23.0 <https://github.com/ThreeMammals/Ocelot/releases/tag/23.0.0>`_, see issue `748 <https://github.com/ThreeMammals/Ocelot/issues/748>`_ and the `23.0 <https://github.com/ThreeMammals/Ocelot/releases/tag/23.0.0>`__ release notes for details.
.. [#f3] ":ref:`routing-upstream-host`" feature was requested as part of `issue 216 <https://github.com/ThreeMammals/Ocelot/pull/216>`_.
.. [#f4] ":ref:`routing-upstream-headers`" feature was proposed in `issue 360 <https://github.com/ThreeMammals/Ocelot/issues/360>`_, and released in version `24.0 <https://github.com/ThreeMammals/Ocelot/releases/tag/24.0.0>`_.
.. [#f5] ":ref:`routing-security-options`" feature was requested as part of `issue 628 <https://github.com/ThreeMammals/Ocelot/issues/628>`_ (of `12.0.1 <https://github.com/ThreeMammals/Ocelot/releases/tag/12.0.1>`_ version), then redesigned and improved by `issue 1400 <https://github.com/ThreeMammals/Ocelot/issues/1400>`_, and published in version `20.0 <https://github.com/ThreeMammals/Ocelot/releases/tag/20.0.0>`_ docs.
.. [#f6] ":ref:`routing-dynamic`" feature was requested as part of `issue 340 <https://github.com/ThreeMammals/Ocelot/issues/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
Loading