Indiko.Hosting.Gateway 2.1.0

Indiko.Hosting.Gateway

API Gateway hosting implementation using Ocelot for routing, load balancing, and service discovery in microservices architectures.

Overview

This package provides a complete hosting solution for API Gateway applications built on Ocelot, including Consul service discovery integration, request routing, load balancing, and seamless integration with Indiko Blocks.

Features

• Ocelot API Gateway: Full Ocelot integration for API gateway functionality
• Consul Integration: Service discovery using HashiCorp Consul
• Request Routing: Route requests to downstream microservices
• Load Balancing: Distribute requests across multiple service instances
• Forwarded Headers: Support for reverse proxy scenarios with full forwarding
• HTTPS Support: Optional HTTPS redirection
• Configuration-based: Define routes via JSON configuration files
• Dynamic Service Discovery: Automatic service endpoint resolution via Consul

Installation

dotnet add package Indiko.Hosting.Gateway

Quick Start

Minimal Setup

using Indiko.Hosting.Gateway;

// Create your startup class
public class Startup : GatewayStartup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment environment)
        : base(configuration, environment)
    {
    }

    protected override bool AddControllersWithViews => false;
    protected override bool EnableForwardedHeaderOptions => true;
    protected override bool ForceHttps => false; // Usually behind load balancer
}

// Program.cs
class Program
{
    static async Task<int> Main(string[] args)
    {
        return await GatewayHostBootstrapper.Instance.RunAsync<Startup>(args);
    }
}

Configuration Files

appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Ocelot": "Information"
    }
  }
}

ocelot.json

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 5001
        }
      ],
      "UpstreamPathTemplate": "/users/{everything}",
      "UpstreamHttpMethod": [ "Get", "Post", "Put", "Delete" ]
    },
    {
      "DownstreamPathTemplate": "/api/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 5002
        }
      ],
      "UpstreamPathTemplate": "/orders/{everything}",
      "UpstreamHttpMethod": [ "Get", "Post", "Put", "Delete" ]
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "https://api.example.com"
  }
}

ocelot.json with Consul

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/{everything}",
      "DownstreamScheme": "http",
      "ServiceName": "user-service",
      "LoadBalancerOptions": {
        "Type": "RoundRobin"
      },
      "UpstreamPathTemplate": "/users/{everything}",
      "UpstreamHttpMethod": [ "Get", "Post", "Put", "Delete" ]
    },
    {
      "DownstreamPathTemplate": "/api/{everything}",
      "DownstreamScheme": "http",
      "ServiceName": "order-service",
      "LoadBalancerOptions": {
        "Type": "LeastConnection"
      },
      "UpstreamPathTemplate": "/orders/{everything}",
      "UpstreamHttpMethod": [ "Get", "Post", "Put", "Delete" ]
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "https://api.example.com",
    "ServiceDiscoveryProvider": {
      "Scheme": "http",
      "Host": "consul",
      "Port": 8500,
      "Type": "Consul"
    }
  }
}

Key Components

GatewayHostBootstrapper

Singleton bootstrapper for API Gateway applications.

await GatewayHostBootstrapper.Instance.RunAsync<Startup>(args);

GatewayStartup

Abstract base class with Ocelot and Consul configuration.

public class MyGatewayStartup : GatewayStartup
{
    protected override bool EnableForwardedHeaderOptions => true;
    protected override bool ForceHttps => false;
    protected override bool AddControllersWithViews => false;
}

Features in Detail

Request Routing

Route incoming requests to downstream services:

{
  "DownstreamPathTemplate": "/api/v1/products/{id}",
  "DownstreamScheme": "https",
  "DownstreamHostAndPorts": [
    { "Host": "product-api.internal", "Port": 443 }
  ],
  "UpstreamPathTemplate": "/products/{id}",
  "UpstreamHttpMethod": [ "Get" ]
}

Service Discovery with Consul

Automatically discover service instances:

{
  "ServiceName": "product-service",
  "ServiceDiscoveryProvider": {
    "Host": "consul.service.consul",
    "Port": 8500,
    "Type": "Consul"
  }
}

Services register with Consul, and the gateway automatically discovers available instances.

Load Balancing

Distribute requests across multiple instances:

{
  "LoadBalancerOptions": {
    "Type": "RoundRobin"
  }
}

Available Load Balancers:

• LeastConnection - Route to instance with fewest connections
• RoundRobin - Distribute evenly across instances
• NoLoadBalancer - Use first available instance

Rate Limiting

Control request rates per endpoint:

{
  "RateLimitOptions": {
    "ClientWhitelist": [],
    "EnableRateLimiting": true,
    "Period": "1s",
    "PeriodTimespan": 1,
    "Limit": 10
  }
}

Caching

Cache downstream responses:

{
  "FileCacheOptions": {
    "TtlSeconds": 60,
    "Region": "products"
  }
}

Quality of Service

Configure circuit breakers and timeouts:

{
  "QoSOptions": {
    "ExceptionsAllowedBeforeBreaking": 3,
    "DurationOfBreak": 1000,
    "TimeoutValue": 5000
  }
}

Authentication & Authorization

Forward or validate authentication:

{
  "AuthenticationOptions": {
    "AuthenticationProviderKey": "Bearer",
    "AllowedScopes": []
  }
}

Request/Response Transformation

Transform headers and body:

{
  "UpstreamHeaderTransform": {
    "X-Forwarded-For": "{RemoteIpAddress}"
  },
  "DownstreamHeaderTransform": {
    "X-Custom-Header": "CustomValue"
  }
}

Forwarded Headers

When behind a reverse proxy or load balancer:

protected override bool EnableForwardedHeaderOptions => true;

This configures:

• X-Forwarded-For - Client IP address
• X-Forwarded-Proto - Original protocol (http/https)
• X-Forwarded-Host - Original host header

All known networks and proxies are allowed (suitable for internal networks).

Advanced Configuration

Aggregation

Aggregate multiple downstream requests:

{
  "Aggregates": [
    {
      "RouteKeys": [
        "user-details",
        "user-orders"
      ],
      "UpstreamPathTemplate": "/users/{id}/profile"
    }
  ]
}

Custom Middleware

Add custom middleware before Ocelot:

public override void Configure(IApplicationBuilder app, IWebHostEnvironment env, ILoggerFactory logger)
{
    // Add custom middleware before base.Configure
    app.UseMiddleware<MyCustomMiddleware>();
    
    base.Configure(app, env, logger);
}

Additional Services

Add services to the gateway:

public override void ConfigureServices(IServiceCollection services)
{
    base.ConfigureServices(services);
    
    services.AddScoped<IMyService, MyService>();
}

Typical Architecture

???????????
? Client  ?
???????????
     ?
     ?
???????????????????
?  API Gateway    ? (Indiko.Hosting.Gateway)
?   (Ocelot)      ?
???????????????????
     ?
     ????????????????????
     ?                  ?
     ?                  ?
????????????????  ????????????????
? User Service ?  ?Order Service ?
?   (Consul)   ?  ?   (Consul)   ?
????????????????  ????????????????

Configuration Loading

Ocelot configuration is typically loaded from ocelot.json:

// In Program.cs or startup configuration
builder.Configuration.AddJsonFile("ocelot.json");

Environment-specific configurations:

ocelot.json
ocelot.Development.json
ocelot.Production.json

Target Framework

• .NET 10

Dependencies

• Indiko.Hosting.Abstractions
• Indiko.Blocks.Common.Abstractions
• Indiko.Blocks.Common.Management
• Ocelot
• Ocelot.Provider.Consul
• Microsoft.AspNetCore.App

License

See LICENSE file in the repository root.

Related Packages

• Indiko.Hosting.Abstractions - Core hosting abstractions
• Indiko.Blocks.Communication.ServiceToService.Consul - Service-to-service communication
• Indiko.Blocks.Tracing.OpenTelemetry - Distributed tracing for gateway
• Indiko.Blocks.Logging.Serilog - Structured logging

Resources

• Ocelot Documentation
• Consul Documentation