Skip to content

Commit

Permalink
Release 23.4.1 | Routing patch | November'24 release | +semver: patch (
Browse files Browse the repository at this point in the history
…#2215)

* Update docs

* Update build script
  • Loading branch information
raman-m committed Nov 22, 2024
1 parent 7a3771b commit a79ae8a
Show file tree
Hide file tree
Showing 5 changed files with 71 additions and 70 deletions.
40 changes: 10 additions & 30 deletions ReleaseNotes.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,12 @@
## :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}/)
## :package: Routing patch (version {0})
> Read the Docs: [Ocelot 23.4](https://ocelot.readthedocs.io/en/{0}/) with [PDF](https://ocelot.readthedocs.io/_/downloads/en/{0}/pdf/)
> Hot fixed version: [{1}](https://github.com/ThreeMammals/Ocelot/releases/tag/{1})
> Milestone: [November'24](https://github.com/ThreeMammals/Ocelot/milestone/10)
### :information_source: About
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.

### :up: Focus On
<details>
<summary><b>Features</b>: Routing, Core, Rate Limiting, Middleware Injection</summary>
:heart: A heartfelt "Thank You" to **[Guillaume Gnaegi](https://github.com/ggnaegi)** (@ggnaegi)

- [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>

<details>
<summary><b>Documentation</b> for <a href="https://ocelot.readthedocs.io/en/{0}/">v{0}</a></summary>

- [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>
### :information_source: About
Addressed issues:
- #2165
- #2209
- #2212
28 changes: 14 additions & 14 deletions build.cake
Original file line number Diff line number Diff line change
Expand Up @@ -367,20 +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("### Starring :star: aka Release Influencers :bowtie:");
releaseNotes.AddRange(starring);
releaseNotes.Add("");
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("");
// 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}");
// 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
56 changes: 38 additions & 18 deletions docs/features/routing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -385,22 +385,31 @@ Consider the following 2 development scenarios :htm:`&rarr;`
Security Options [#f5]_
-----------------------

Ocelot allows you to manage multiple patterns for allowed/blocked IPs using the `IPAddressRange <https://github.com/jsakamoto/ipaddressrange>`_ package
with `MPL-2.0 License <https://github.com/jsakamoto/ipaddressrange/blob/master/LICENSE>`_.

This feature is designed to allow greater IP management in order to include or exclude a wide IP range via CIDR notation or IP range.
The current patterns managed are the following:

* Single IP: :code:`192.168.1.1`
* IP Range: :code:`192.168.1.1-192.168.1.250`
* IP Short Range: :code:`192.168.1.1-250`
* IP Range with subnet: :code:`192.168.1.0/255.255.255.0`
* CIDR: :code:`192.168.1.0/24`
* CIDR for IPv6: :code:`fe80::/10`
* The allowed/blocked lists are evaluated during configuration loading
* The **ExcludeAllowedFromBlocked** property is intended to provide the ability to specify a wide range of blocked IP addresses and allow a subrange of IP addresses.
Default value: :code:`false`
* The absence of a property in **SecurityOptions** is allowed, it takes the default value.
Ocelot enables the management of multiple patterns for allowed and blocked IPs using the `IPAddressRange <https://github.com/jsakamoto/ipaddressrange>`_ package, which is licensed under the `MPL-2.0 license <https://github.com/jsakamoto/ipaddressrange/blob/master/LICENSE>`_.

This feature is designed to enhanced IP management, allowing for the inclusion exclusion of a broad IP range through CIDR notation or specific IP ranges.
The current managed patterns are as follows:

.. list-table::
:widths: 35 65
:header-rows: 1

* - *IP Rule*
- *Example*
* - Single IP
- ``192.168.1.1``
* - IP Range
- ``192.168.1.1-192.168.1.250``
* - IP Short Range
- ``192.168.1.1-250``
* - IP Subnet
- ``192.168.1.0/255.255.255.0``
* - CIDR IPv4
- ``192.168.1.0/24``
* - CIDR IPv6
- ``fe80::/10``

Here is a quick example:

.. code-block:: json
Expand All @@ -412,9 +421,17 @@ The current patterns managed are the following:
}
}
Please **note** that:

* The allowed/blocked lists are evaluated during configuration loading
* The ``ExcludeAllowedFromBlocked`` property is intended to provide the ability to specify a wide range of blocked IP addresses and allow a subrange of IP addresses.
Default value: :code:`false`
* The absence of a property in *Security Options* is allowed, it takes the default value.
* The *Security Options* can be configured **globally** in the ``GlobalConfiguration`` JSON; however, it is ignored if overriding options are specified at the route level [#f6]_.

.. _routing-dynamic:

Dynamic Routing [#f6]_
Dynamic Routing [#f7]_
----------------------

The idea is to enable dynamic routing when using a :doc:`../features/servicediscovery` provider so you don't have to provide the Route config.
Expand All @@ -426,7 +443,8 @@ See the :ref:`sd-dynamic-routing` docs if this sounds interesting to you.
.. [#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`.
.. [#f6] Global ":ref:`routing-security-options`" feature was requested as part of issue `2165`_ , and released in version `23.4.1`_.
.. [#f7] ":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
Expand All @@ -441,10 +459,12 @@ See the :ref:`sd-dynamic-routing` docs if this sounds interesting to you.
.. _952: https://github.com/ThreeMammals/Ocelot/issues/952
.. _1174: https://github.com/ThreeMammals/Ocelot/issues/1174
.. _1400: https://github.com/ThreeMammals/Ocelot/issues/1400
.. _2165: https://github.com/ThreeMammals/Ocelot/issues/2165
.. _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
.. _23.4.1: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.1
2 changes: 1 addition & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. _23.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.0
.. _23.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.1

############################
Ocelot `23.4`_ Documentation
Expand Down
15 changes: 8 additions & 7 deletions docs/releasenotes.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@
.. _@jlukawska: https://github.com/jlukawska
.. _@kesskalli: https://github.com/kesskalli

.. _23.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.0
.. _23.4: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.1
.. _23.4.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.0
.. _23.4.1: https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.1

.. _1111: https://github.com/ThreeMammals/Ocelot/issues/1111
.. _1307: https://github.com/ThreeMammals/Ocelot/pull/1307
Expand All @@ -25,23 +26,23 @@ 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.4.0`_ includes several patches, the history of which is provided below.
The major version `23.4.0`_ includes several patches, the history of which is provided below.

.. .. admonition:: Patches
.. admonition:: Patches

.. - `23.3.3`_, on Jun 11, 2024. Technical release with DevOps patch.
- `23.4.1`_, on Nov 22, 2024: Routing patch.

.. _release-notes:

📢 Release Notes
-----------------

| Release Tag: `23.4.0`_
| Release Codename: `Make Guillaume Great Again! <https://github.com/ThreeMammals/Ocelot/commits?author=ggnaegi>`_
| Release Codename: `McDonald's <https://www.youtube.com/watch?v=_PgYAPdOs9M>`_
:htm:`<details><summary>With codename decoding links:</summary>`
:htm:`<details><summary>With release jokes:</summary>`

- **for men**: The abbreviation "MGGA" is reminiscent of the `MAGA slogan <https://www.bing.com/search?q=make+america+great+again+slogan>`_
- **for men**: Wearing a cap with the `MAGA slogan <https://www.bing.com/search?q=make+america+great+again+slogan>`_ is encouraged when visiting McDonald's.
- **for women**: Donald is fond of caps, particularly the `MAGA cap <https://www.bing.com/search?q=make+america+great+again+cap>`_, and it's amusing to see children's reactions when `We Ask Kids How Mr.D is Doing <https://www.youtube.com/watch?v=XYviM5xevC8>`_?
- **for black men**: Here are some highlights of Donald's antics aka Mr. D:

Expand Down

0 comments on commit a79ae8a

Please sign in to comment.