How threemammals/ocelot works
Project Type and Purpose
• Project Type: An API Gateway built as a series of ASP.NET Core middleware components.
• Purpose: To act as a unified entry point for microservices architectures. It routes, aggregates, transforms, and secures HTTP requests and responses between clients and multiple downstream services. It also supports additional features such as caching, rate limiting, load balancing, service discovery, and integration with logging/tracing systems.
File Structure
• The top-level directories (“src”, “samples”, “test”, “docs”, “docker”, “.github”, etc.) indicate a large, solution-oriented project with multiple assemblies.
• In “src” you see various projects:
– Core functionality under Ocelot (middleware, configuration, request handling, error handling, etc.).
– Provider integrations like Consul, Eureka, Kubernetes, Polly for resiliency, and tracing integrations (Butterfly, OpenTracing).
– A set of “Configuration” projects that build and validate Ocelot’s JSON (or file-based) configuration into the internal representation.
– Middleware pipelines for authentication, authorization, rate limiting, caching, header/query transformation, etc.
• The “samples” directory provides multiple usage examples (Basic, Configuration, Eureka, GraphQL, Kubernetes, ServiceDiscovery, ServiceFabric, Web) showing how Ocelot integrates with different technologies.
• The “test” directory holds unit, integration, and acceptance tests that validate the behavior of individual middlewares and pipelines.
README for Additional Insights
• The README clearly lays out the Ocelot pipeline as a sequence of ASP.NET Core middleware.
• It details key features such as Routing, Request Aggregation, authentication/authorization, caching, QoS, load balancing, service discovery, and logging/tracing.
• Modular pattern where each middleware is responsible for a transformation or function on the request or response, culminating in the delegation to the downstream service.
a. Main Components
– Client/Consumer:
• External clients sending HTTP/HTTPS requests.
– API Gateway (Ocelot):
• Entry Point Middleware Pipeline:
▪ Authentication Middleware (includes integration with IdentityServer or other token providers)
▪ Authorization Middleware (claim and scope based checks)
▪ Routing and Request Aggregation Middleware (decides how and where to route requests)
▪ Transformation Middleware (headers, queries, claims, etc.)
▪ Caching Middleware (output caching handling downstream responses)
▪ Rate Limiting Middleware (to throttle requests)
▪ Load Balancing Component (integrates with various balancing strategies such as Round Robin, Least Connection, Sticky Sessions)
▪ Quality of Service (QoS) using Polly policy integration for resilience
▪ Service Discovery Providers (to locate downstream services via Consul, Eureka, Kubernetes, Service Fabric, etc.)
▪ Request/Response Mediation (mapping HttpRequest to HttpRequestMessage, and vice versa)
▪ Logging/Tracing (tracing integration using Butterfly or OpenTracing middlewares)
– Downstream Services:
• Microservices that handle business logic. The gateway eventually routes requests to these services.
– Configuration Management:
• Ocelot’s configuration repository (file-based and/or dynamic via providers like Consul).
– Supporting Infrastructure:
• Dependency injection mechanism (via the Ocelot Builder and administration builder).
• Custom middleware and delegating handlers that can be injected or extended by users.
b. Relationships and Interactions
– Data flows from external clients into the API gateway.
– Within the gateway, the middleware pipeline sequentially transforms the request (authentication → authorization → routing/aggregation → caching → load balancing).
– The gateway then forms a proper HttpRequestMessage and communicates with one or more downstream services.
– The response flows back through the pipeline where output transformation (header, query, claims adjustments) and logging/tracing occurs.
– The configuration system and providers (like file repositories or dynamic sources from Consul/Eureka) feed into the pipeline setup.
c. Architectural Patterns and Design Principles
– Middleware Pattern: The core design relies on a chain of middleware components forming a pipeline.
– Dependency Injection: For injecting providers, handlers, and middleware components.
– Separation of Concerns: Different middleware handles routing, aggregation, rate limiting, caching, and error handling separately.
– Extensibility: Custom middleware and delegating handlers act as extension points.
– Resilience: Integrates with Polly for QoS and handles load balancing via multiple strategies.
d. Relevant Technologies, Frameworks, or Libraries
– ASP.NET Core (Middleware, DI, HTTP pipeline).
– Polly for resilience and QoS standards.
– Service Discovery libraries: Consul, Eureka, Kubernetes, Service Fabric.
– Logging/Tracing: Butterfly, OpenTracing.
– .NET multi-targeting practices (net8.0/net9.0 support)
– Docker for containerization and build scripts provided in the “docker” directory.