ThreeMammals/Ocelot 24.1.0

on GitHub

This update brings changes to the Dynamic Route Schema and Global Configuration Schema, while the Route Schema stays the same apart from deprecation updates. All work was coordinated under issue #585, which addressed the challenges of configuring Ocelot's most popular features globally before version 24.1, when dynamic routing gained global configuration partial support, but static routing mostly lacked it. A key outcome of #585 is the ability to override global configuration options within the DynamicRoutes collection. This ongoing issue will continue to require attention, as adapting static route global configurations for dynamic routing is complex and, in some cases, impossible. This will be a challenge for future Ocelot releases and the community.

The Ocelot.Provider.Kubernetes package now features a new WatchKube provider for Kubernetes service discovery. This provider is a great fit for high-load environments where the older Kube and PollKube providers struggle to handle heavy traffic, often leading to increased log errors, HTTP 500 issues, and potential Ocelot instance failures. WatchKube is the next step in the evolution of these providers, leveraging the reactive capabilities of the KubeClient API. For guidance on choosing the right provider for your Kubernetes setup, check out the "Comparing providers" section in the documentation.

In the past, the Timeout setting in the Route Schema didn't actually stop requests, defaulting instead to a fixed 90 seconds. Custom timeouts were handled using the Quality of Service Timeout strategy, and this only applied if Polly and the Ocelot.Provider.Polly package were used. Now, the Timeout option (in seconds) can be set at the route, global, and QoS levels. The Global Configuration Schema and Dynamic Route Schema also include the new Timeout setting, making it possible to configure default timeouts for dynamic routing as well.

Starting with version 24.1, two new parameters in QoSOptions, FailureRatio and SamplingDuration, let you fine-tune the behavior of the Circuit Breaker strategy. Both can be configured globally, even with dynamic routing.
Please note that DurationOfBreak, ExceptionsAllowedBeforeBreaking, and TimeoutValue are now deprecated in 24.1, so check the QoSOptions Schema documentation for details.

The updated docs now highlight these deprecated options with multiple notes and warnings. The v24.1 deprecation process will wrap up in the upcoming .NET 10 release. Due to the Obsolete attributes, C# developers will notice several build warnings during compilation.

The project was removed from the main repo and moved to its own Ocelot.Testing repository. This change allows the Ocelot.Testing package to be shared independently for extension package delivery. The Ocelot team also plans to deprecate more projects and move them to separate repos because: a) despite the fact that a monorepo enables faster builds and quicker delivery; b) but the release process can be delayed by missing versions of integrated libraries in extension packages. The goal is for the Ocelot repo to only contain essential projects, avoiding delays caused by integrated package release schedules. Legacy or abandoned integrated packages should be deprecated and maintained in their own repos with independent release cycles.

The Global Configuration Schema now includes new DownstreamHeaderTransform and UpstreamHeaderTransform options. These work only with static routes, meaning the Routes collection (see Route Schema). They aren't supported for dynamic routes because they're not part of the Dynamic Route Schema, and Ocelot Core doesn't read global configuration of this feature in dynamic routing mode. This is noted in the Roadmap documentation.

The Global Configuration Schema now includes a new AuthenticationOptions property for setting up static routes globally. This also introduces the AllowAnonymous boolean option within AuthenticationOptions to control static route authentication. Later, PR #2336 extended global authentication support to dynamic routes.
Note: The AuthenticationProviderKey option is deprecated in version 24.1—see the AuthenticationOptions Schema documentation for details.

The Global Configuration Schema now includes a new RateLimitOptions property for both static and dynamic routes. Previously, global configuration was available through RateLimitOptions in dynamic routing mode, while route overriding used the now-deprecated RateLimitRule from the Dynamic Route Schema.
This marks the second major overhaul of the Rate Limiting feature since the first update in PR #1592. A new Wait option has been added, replacing the deprecated PeriodTimespan, to enhance the Fixed Window algorithm. The full list of deprecated options can be found in the Deprecated Options documentation.

The Global Configuration Schema now includes a new LoadBalancerOptions property for both static and dynamic routes. Previously, global configuration was available through LoadBalancerOptions in dynamic routing mode without dynamic route overrides. Starting with version 24.1, the Dynamic Route Schema also supports LoadBalancerOptions for overriding, and global configuration for static routes is now supported as well.

The Global Configuration Schema now includes a new CacheOptions property for both static and dynamic routes. Global configuration has been available for static routes since version 23.3, but starting with version 24.1, the Dynamic Route Schema also supports CacheOptions for overriding.
Note that the FileCacheOptions property in the Route Schema (static routes) is deprecated in version 24.1. For more details, see the caching Configuration documentation.

The Global Configuration Schema now includes a new HttpHandlerOptions property for both static and dynamic routes. Previously, global configuration was available through HttpHandlerOptions in dynamic routing mode without dynamic route overriding. Starting with version 24.1, the Dynamic Route Schema also supports HttpHandlerOptions for overriding, and global configuration is now available for static routes as well.

The Global Configuration Schema now includes a new AuthenticationOptions property for both static and dynamic routes. Starting with version 24.1, the Dynamic Route Schema also supports AuthenticationOptions to override global settings.
Note that the AuthenticationProviderKey option is deprecated in version 24.1, so check the AuthenticationOptions Schema documentation for details.

The Global Configuration Schema now includes a new QoSOptions property for both static and dynamic routes. Previously, global configuration was available through QoSOptions in dynamic routing mode without the option for dynamic route overrides. Starting with version 24.1, the Dynamic Route Schema supports QoSOptions for overriding, and global configuration support is now available for static routes as well.
Note that the DurationOfBreak, ExceptionsAllowedBeforeBreaking, and TimeoutValue options are deprecated in version 24.1. For details, see the QoSOptions Schema documentation.

These efforts kept the CI/CD builds in GitHub Actions stable, targeting the alpha release of version 24.1. The CI/CD environment was set up and tested GH-Actions workflows in advance for the beta release, which is the goal of PR #2347.

This update removes the troublesome System.Net.WebSockets.WebSocketException from logs, preventing Ocelot from running into 500 status disasters. The issue stemmed from client-side or network events that Ocelot's WebSocketsProxyMiddleware couldn't anticipate on the server side. The patch now checks for incorrect connection statuses, attempting to close the connection and end server-side tasks gracefully without errors.

This update fixes the PollKube provider to address a bug with the first cold request, where the winning thread got an empty collection before the initial callback was triggered. The solution is to call the integrated discovery provider for the first cold request when the queue is empty.

Starting with version 24.1, Ocelot now supports RFC 8693 (OAuth 2.0 Token Exchange) for the scope claim in the ScopesAuthorizer service, also referred to as the IScopesAuthorizer service in the DI container.

• _{6be80d8 by Raman Maksimchuk on Wednesday, December 24 at 10:05 →}
  #2343 Release 24.1 Beta.1 (#2348)
• _{2f317b7 by Raman Maksimchuk on Tuesday, December 23 at 17:22 →}
  #2343 Release 24.1 Beta | +semver: minor (#2347)
• _{fede41d by Raman Maksimchuk on Friday, December 19 at 17:19 →}
  #2343 Pre-release 24.1 | +semver: patch (#2345)
• _{fff9cf7 by Raman Maksimchuk on Tuesday, December 9 at 21:20 →}
  Follow-up on #2335 and #2339: Stabilize flaky tests in the CI/CD environment (#2342)
• _{adc34ec by Mehmet Yasin AKAR on Sunday, December 7 at 21:16 →}
  #913 Support RFC 8693 (OAuth 2.0 Token Exchange) for the "scope" claim in ScopesAuthorizer (#1478)
• _{35dbc9d by Raman Maksimchuk on Thursday, December 4 at 17:25 →}
  #585 #2338 Quality of Service global configuration (#2339)
• _{4730613 by Raman Maksimchuk on Monday, November 24 at 9:48 →}
  #585 #2316 Authentication global configuration (#2336)
• _{1fdf6c2 by Raman Maksimchuk on Tuesday, November 11 at 13:45 →}
  #2304 Utilize ConcurrentQueue{T} for managing service versions during polling by the PollKube discovery provider (#2335)
• _{9127387 by Raman Maksimchuk on Sunday, November 9 at 22:36 →}
  #585 #2320 Http handler global configuration (#2332)
• _{e3ad51c by Raman Maksimchuk on Monday, October 27 at 18:09 →}
  #585 #2330 Caching global configuration (#2331)
• _{f758ba7 by Raman Maksimchuk on Thursday, October 23 at 00:36 →}
  #585 #2319 Load Balancer global configuration (#2324)
• _{3c6f648 by Raman Maksimchuk on Thursday, September 25 at 18:04 →}
  #1440 #2318 Remove the GH Actions step /usr/lib/dotnet since the old DevOps lifehack is no longer necessary
• _{e6b2023 by Raman Maksimchuk on Thursday, September 25 at 17:37 →}
  #1440 Update license file (#2318)
• _{d5e6d9a by Milad Rivandi on Tuesday, September 23 at 10:55 →}
  #585 #1229 #1598 #1915 Rate limiting global configuration (#2294)
• _{265f9b4 by jlukawska on Sunday, August 10 at 21:00 →}
  #842 #1414 Introduce AllowAnonymous authentication option with global AuthenticationOptions configuration (#2114)
• _{c7b9c91 by Harris Zhang on Tuesday, August 5 at 18:13 →}
  Use the appropriate class name as a type parameter to create a named logger through the factory in the ConfigurationMiddleware constructor (#2306)
• _{c29d821 by Mark Bøg Lønquist on Saturday, July 26 at 15:38 →}
  #1658 Add global configuration for Headers Transformation (#1659)
• _{c721273 by Raynald Messié on Saturday, July 19 at 18:21 →}
  #2080 Add new FailureRatio and SamplingDuration V8 parameters to fine-tune Polly's circuit-breaker strategy via route-level and global QoS options (#2081)
• _{7c583bf by Zhannur Akhmetkhanov on Friday, July 4 at 21:10 →}
  #1314 #1869 #2072 Default timeout for all levels, including route, global, and QoS (#2073)
• _{8143d56 by Nikolay on Monday, June 16 at 16:16 →}
  #2168 A brand-new WatchKube provider for Kubernetes service discovery (#2174)
• _{ed8ba5b by Raman Maksimchuk on Thursday, June 12 at 22:45 →}
  Follow up #2091 Update the Develop & Release workflows to include two actions: adding DNS records and installing certificates
• _{e527f27 by Zhannur Akhmetkhanov on Friday, June 13 at 1:01 →}
  #930 Try to close WebSocket destination when state is Open or CloseReceived (#2091)
• _{0b794b3 by Raman Maksimchuk on Tuesday, May 27 at 13:33 →}
  Publish Administration docs of the new Ocelot.Administration.IdentityServer4 package
• _{cae58d5 by Raman Maksimchuk on Friday, May 23 at 12:52 →}
  Deprecate the Ocelot.Testing project in favor of its NuGet package (#2295)
• _{e78fe42 by Raman Maksimchuk on Tuesday, April 22 at 19:56 →}
  Rewrite the README and roll back the status badge targets to develop

• Deprecate the Ocelot.Testing project in favor of its NuGet package by @raman-m in #2295
• #930 Try to close WebSocket destination when state is Open or CloseReceived by @hogwartsdeveloper in #2091
• #2168 A brand-new WatchKube provider for Kubernetes service discovery by @kick2nick in #2174
• #1314 #1869 #2072 Default timeout for all levels, including route, global, and QoS by @hogwartsdeveloper in #2073
• #2080 Add new FailureRatio and SamplingDuration V8 parameters to fine-tune Polly's circuit-breaker strategy via route-level and global QoS options by @RaynaldM in #2081
• #1658 Add global configuration for Headers Transformation by @marklonquist in #1659
• Use the appropriate class name as a type parameter to create a named logger through the factory in the ConfigurationMiddleware constructor by @harris2012 in #2306
• #842 #1414 Introduce AllowAnonymous authentication option with global AuthenticationOptions configuration by @jlukawska in #2114
• #585 #1229 #1598 #1915 Rate limiting global configuration by @MiladRv in #2294
• #1440 Update license file by @raman-m in #2318
• #585 #2319 Load Balancer global configuration by @raman-m in #2324
• #585 #2330 Caching global configuration by @raman-m in #2331
• #585 #2320 Http handler global configuration by @raman-m in #2332
• #2304 Utilize ConcurrentQueue<T> for managing service versions during polling by the PollKube discovery provider by @raman-m in #2335
• #585 #2316 Authentication global configuration by @raman-m in #2336
• #585 #2338 Quality of Service global configuration by @raman-m in #2339
• #913 Support RFC 8693 (OAuth 2.0 Token Exchange) for the "scope" claim in ScopesAuthorizer by @mehyaa in #1478
• #2343 Release 24.1 Beta | +semver: minor by @raman-m in #2347
• #2343 Release 24.1 Beta.1 by @raman-m in #2348
• Release v24.1 | Summer-Autumn 2025 | Globality release by @raman-m in #2349