ThreeMammals/Ocelot

Ocelot is an API gateway and middleware for .NET that routes, aggregates, and secures HTTP requests. It provides features such as URL path manipulation, IP-based access control, OAuth 2.0 scope validation, and configurable caching. The system supports service discovery via Eureka and Kubernetes, handles GraphQL queries, and manages configuration through file-based or in-memory models. It includes infrastructure for performance benchmarking, manual testing, and comprehensive acceptance and unit testing.

6 changes.

This period focused on removing obsolete prototype code and legacy project scaffolding to clean up the repository structure. The team modernized the development environment by standardizing tooling, updating to .NET 9 for Docker builds, and migrating the build system to .NET global tools.

16 changes.

The project underwent a comprehensive architectural overhaul to support .NET 8 through 10, featuring a complete reorganization of source code into modular folders and a refactored configuration system with fluent builders. This period also introduced significant enhancements to the middleware pipeline, including structured error handling, IP-based security policies, and a new authorization middleware, alongside extensive updates to testing infrastructure and performance benchmarking.

Added five new sample projects to the \samples\ directory to demonstrate Ocelot usage across different scenarios. The Basic sample shows a minimal setup with a single \ocelot.json\ file. The Configuration sample demonstrates merging multiple \ocelot.\*.json\ files and accessing custom properties via \IConfiguration\ and Newtonsoft JSON helpers. The Eureka sample illustrates service discovery using the Eureka provider with Polly QoS and caching. The GraphQL sample integrates \graphql-dotnet\ via a custom \DelegatingHandler\ to handle GraphQL queries within Ocelot. The Kubernetes sample provides examples for service discovery using the KubeClient provider, including various configuration patterns for pod service accounts and manual options binding.

samples · high confidence

A new AuthorizationMiddleware has been introduced to handle route-level authorization by enforcing both OAuth 2.0 scopes and custom claims. The middleware now validates that user tokens contain at least one allowed scope (supporting RFC 8693 space-separated values) and verifies that user claims match route-specific requirements, including dynamic claim matching against URL path placeholders. This change introduces dedicated authorizers (ScopesAuthorizer and ClaimsAuthorizer) and specific error types (ScopeNotAuthorizedError, ClaimValueNotAuthorizedError, etc.) to provide clear feedback when authorization fails.

src/Authorization · high confidence

Added a new benchmark project in the \benchmark\ directory to measure Ocelot's performance characteristics. The suite includes benchmarks for URL path matching, middleware execution (DownstreamRouteFinder, ExceptionHandler), logging overhead (comparing Microsoft.Extensions.Logging and Serilog across various log levels), and payload handling (JSON and binary payloads of varying sizes). It also includes an 'AllTheThings' end-to-end benchmark and a response benchmark, utilizing BenchmarkDotNet for analysis.

benchmark · high confidence

A new manual test application has been added to the 'manual' directory, providing a self-hosted environment for developers to interact with and verify Ocelot's behavior. This includes a console-based launcher (Program.cs) to run basic Ocelot setups or manual tests, configuration files (ocelot.json, ocelot.identityserver4.json) for routing and authentication scenarios, and specific test assets like a Postman collection and an HTML page for WebSocket debugging (Bug 930). The application is structured to be built and run via Docker, offering a convenient way to test the gateway locally without relying on external acceptance test infrastructure.

manual, src · high confidence

The initial prototype implementation for the Ocelot.ApiGateway module has been removed. This includes the deletion of the entry point (Program.cs), startup configuration (Startup.cs), and a basic routing setup that previously returned a static 'Hi, Tom!' response. Additionally, the Dockerfile, project.json, and web.config files defining the .NET Core 1.0 rc2 build and deployment environment for this specific gateway component have been deleted, indicating the abandonment of this early experimental structure.

src/Ocelot.ApiGateway · high confidence

The src/Ocelot.Library project has been removed, including its project.json configuration, .gitignore, and the empty RouterMiddleware.cs class. This cleanup eliminates obsolete .NET Standard 1.5 scaffolding and associated build artifacts from the repository.

src/Ocelot.Library · high confidence

The configuration system in src/Configuration has been restructured to use a dedicated builder pattern and a new set of immutable options classes. New classes such as AuthenticationOptions, CacheOptions, and MetadataOptions replace previous structures, while corresponding builders (e.g., DownstreamRouteBuilder, MetadataOptionsBuilder) provide a fluent API for assembling route and service provider settings. This change introduces a new Creator layer (e.g., ConfigurationCreator, AggregatesCreator) to handle the translation of file-based configurations into these internal objects, and adds a ChangeTracking subsystem (OcelotConfigurationMonitor, OcelotConfigurationChangeToken) to manage configuration updates via IOptionsMonitor.

src/Configuration · high confidence

The codebase has been reorganized to improve modularity: path manipulation logic (including the new \ClaimsToDownstreamPathMiddleware\ and \ChangeDownstreamPathTemplate\) is now in \src/DownstreamPathManipulation\, route finding (static and discovery) is in \src/DownstreamRouteFinder\, and response aggregation is in \src/Multiplexer\. This change moves these components into their own folders, aligning the file structure with their functional responsibilities.

src/DownstreamPathManipulation, src/DownstreamRouteFinder, src/Multiplexer · high confidence

The Docker build infrastructure has been updated to support .NET 9, introducing new base images (Dockerfile.base and Dockerfile.windows) that use the .NET 9 SDK as the primary runtime while retaining .NET 8 for compatibility. The Linux build image now relies on Alpine with .NET 9, and the Windows image uses Nano Server 2022 with .NET 9. Additionally, the repository now includes archived 'outdated' Dockerfiles for previous .NET 6/7/8 configurations to preserve historical build capabilities, and build scripts (build.sh, build-windows.sh) have been updated to tag and push these new .NET 9-specific images.

docker · high confidence

This change introduces a new, structured error model in the Ocelot pipeline. A new \Error\ base class and \OcelotErrorCode\ enum replace ad-hoc error handling, allowing errors to carry specific codes, messages, and HTTP status codes. Specifically, downstream request timeouts now return a 504 Gateway Timeout status code to align with RFC 9110, and client-cancelled requests return 499. The \ExceptionHandlerMiddleware\ now catches unhandled exceptions and logs detailed inner-exception chains, while the \ResponderMiddleware\ uses a new \ErrorsToHttpStatusCodeMapper\ to translate these structured errors into appropriate HTTP responses (e.g., 401, 403, 404, 500) before sending them to the client.

src/Errors · high confidence

The build system has been updated to use .NET global tools instead of previous methods. A new dotnet-tools.json file defines specific versions for Cake (6.3.0), ReportGenerator (5.5.11), and GitVersion (6.8.2). Additionally, a GitVersion configuration file (GitVersion.yml) has been added to set ContinuousDelivery mode, and a Coverlet runsettings file (coverlet.runsettings) has been introduced to configure code coverage collection, specifically excluding the Ocelot.Testing assembly and test assemblies from coverage metrics.

.config · high confidence

Ocelot now introduces a new \IOcelotBuilder\ interface and \OcelotBuilder\ implementation to centralize service registration, replacing the previous direct \IServiceCollection\ extension pattern. This change adds a \MergeOcelotJson\ enum that allows users to choose whether to merge multiple \ocelot.\*.json\ configuration files into the primary file or keep them merged in memory. The \ConfigurationBuilderExtensions\ class now handles the discovery and merging of primary, global, and environment-specific configuration files using Newtonsoft's \JToken\ merge functionality, and \ConfigurationExtensions\ provides helper methods to access specific configuration sections like routes and aggregates.

src/DependencyInjection · high confidence

The Ocelot request pipeline has been restructured into a new, extensible middleware chain defined in \src/Middleware\. This includes a \ConfigurationMiddleware\ to inject internal configuration into the HTTP context, a \BaseUrlFinder\ to resolve base URLs from file or memory configuration, and a \DownstreamResponse\ wrapper to properly manage downstream connection resources. The pipeline order is now explicitly configured in \OcelotPipelineExtensions\, placing security checks after multiplexing and before header transformation. Additionally, a new security subsystem in \src/Security\ introduces \SecurityMiddleware\ and an \ISecurityPolicy\ interface, enabling IP-based access control via \IPSecurityPolicy\ (allow/block lists) that returns 403 Forbidden for unauthorized requests, including specific handling for WebSocket upgrade failures.

src/Middleware, src/Security · high confidence

The HTTP requester implementation has been rewritten to use a pooled HttpMessageInvoker (MessageInvokerPool) instead of creating new handlers per request, improving performance and resource management. The new architecture introduces a DelegatingHandlerFactory to manage handler chains (tracing, QoS, custom handlers) and a dedicated HttpExceptionToErrorMapper that maps specific exceptions to precise HTTP status codes, including 504 Gateway Timeout for timeouts, 400 Bad Request for invalid headers, 413 Content Too Large, and 499 for cancelled requests, replacing the previous generic 502/500 responses.

src/Requester · high confidence

The project's source files have been reorganized into a new directory layout, moving components such as authentication, caching, claims, URL creation, and header handling into dedicated subfolders (e.g., \src/Authentication\, \src/Cache\, \src/Claims\, \src/Headers\). This structural change updates the namespaces and file paths for these middleware and infrastructure classes without altering their external behavior.

(repo-wide) · high confidence

The repository now includes standardized development tooling to improve consistency and compatibility. A comprehensive .editorconfig file enforces .NET and C\# coding conventions, indentation, and formatting rules across all source files. A .gitattributes file ensures correct line-ending normalization (CRLF for source/config files, LF for scripts) and prevents binary file corruption. Additionally, the project has migrated to the Visual Studio 2026 solution file format (.slnx), introducing Ocelot.slnx and Ocelot.Samples.slnx to replace legacy .sln files, and a .dockerignore file has been added to exclude build artifacts and temporary directories from Docker contexts.

(repo-wide) · high confidence

The Administration module has been reorganized into a new folder structure, introducing dedicated classes for administration paths and configuration management. To improve security and reduce noise in API documentation, the FileConfiguration and OutputCache controllers are now explicitly hidden from Swagger and OpenAPI views via the \[ApiExplorerSettings(IgnoreApi = true)\] attribute, while retaining their authorization requirements. The FileConfigurationController exposes GET and POST endpoints for retrieving and setting file-based configuration, and the OutputCacheController provides a DELETE endpoint to clear cache regions.

src/Administration · high confidence

Acceptance tests migrated to .NET 10 and new folder structure; Added unit tests for administration, authentication, authorization, and caching components; Cleanup of obsolete test project files; New Ocelot.Testing library for acceptance and unit tests.

The Ocelot project, including its core library, testing utilities, samples, and documentation tooling, has been updated to support .NET 8.0, 9.0, and 10.0. This change aligns the solution with the latest .NET SDK versions and updates associated NuGet packages, such as Microsoft.Extensions.\* and Microsoft.AspNetCore.\*, to versions compatible with these frameworks.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 50 → 45 (-5.5)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 67 → 60 (-6.6)
• Architecture 80 → 82 (+1.8)
• Maturity 68 → 67 (-1.3)
• Readiness 60 → 52 (-8.6)
• Security 39 → 31 (-7.4)
• Performance 54 → 54 (-0.3)

• BarePragmaDisable (src/RateLimiting/RateLimiting.cs)
• Bounded contexts not declared
• CommentedOutCode (acceptance/AggregateTests.cs)
• Critical IaC: DS-0031 (docker/Dockerfile.build)
• Critical IaC: DS-0031 (docker/Dockerfile.release)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 22 more

• Boundary-crossing change coupling: HttpExceptionToErrorMapper.cs ↔ ErrorsToHttpStatusCodeMapper.cs (src/Requester/HttpExceptionToErrorMapper.cs)
• CommentedOutCode (.github/workflows/pr.yml)
• CommentedOutCode (.github/workflows/pr.yml)
• CommentedOutCode (.github/workflows/pr.yml)
• CommentedOutCode (.github/workflows/pr.yml)
• CommentedOutCode (.github/workflows/pr.yml)
• CommentedOutCode (.github/workflows/release.yml)
• CommentedOutCode (.github/workflows/release.yml)
• CommentedOutCode (acceptance/Administration/OcelotBuilderExtensions.cs)
• CommentedOutCode (acceptance/Administration/OcelotBuilderExtensions.cs)
• CommentedOutCode (acceptance/Administration/OcelotBuilderExtensions.cs)
• CommentedOutCode (acceptance/Aggregation/AggregateTests.cs)
• CommentedOutCode (acceptance/Request/StreamContentTests.cs)
• CommentedOutCode (src/Configuration/File/FileRateLimitByHeaderRule.cs)
• Critical IaC: DS-0031 (docker/Dockerfile.build)
• Critical IaC: DS-0031 (docker/Dockerfile.build)
• Critical IaC: DS-0031 (docker/Dockerfile.release)
• Critical IaC: DS-0031 (docker/Dockerfile.release)
• Critical IaC: DS-0031 (docker/Dockerfile.release)
• Critical IaC: DS-0031 (docker/Dockerfile.release)
• …and 96 more

• 13 commits — 13 feature/other, 0 fixes

• docs/features — 4 commits
• (root) — 2 commits
• .github/workflows — 2 commits
• (repo) — 1 commit
• acceptance/Configuration — 1 commit
• docs/building — 1 commit
• docs/index.rst — 1 commit
• samples/Eureka — 1 commit

• change: #1687 Return 504 Gateway Timeout for downstream request timeouts according to RFC 9110 (#2420)
• change: #679 Preserve URL-shaped keys in RouteClaimsRequirement authorization option (#2414)
• change: Don't upload code coverage for Release-mode DLLs as a second uploaded report, since it breaks the coverage process for Debug DLLs
• change: Finalize the docs for version 25.0
• change: IDE0130 Namespace Ocelot.AcceptanceTests.* does not match folder structure, expected Ocelot.Acceptance.*
• change: Merge branch 'release/25.0' into develop
• change: Ref SDK 10.0.401 (Runtime 10.0.12) to release Ocelot v25.0.1 and Ocelot.Testing v25.0.1
• change: Release Ocelot.Discovery.Eureka v25.0.1
• change: Release Ocelot.Discovery.KubeClient v25.0.1
• change: Release Ocelot.QualityOfService.Polly v25.0.1
• change: Release version 25.0.1 for SDK 10.0.401 | +semver: patch
• change: Update Release Notes doc on ocelot.readthedocs.io for the develop version to start the v25.1 dev cycle
• change: Update the coverage.sh step script to look up testing results in the artifacts folder (#2424)

• Unchanged — 15 HTTP endpoints

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

ThreeMammals/Ocelot was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.