Indiko.Hosting.Gateway 2.7.8

Indiko.Hosting.Gateway

A production-ready API Gateway hosting package built on Ocelot and HashiCorp Consul, with Indiko Blocks integration and a flexible host builder.

Features

• Ocelot API Gateway — route upstream requests to downstream microservices via JSON configuration
• Consul service discovery — automatic endpoint resolution for registered Consul services
• Forwarded headers — full X-Forwarded-* support with KnownNetworks and KnownProxies cleared for trusted-proxy deployments
• ocelot.json auto-loading — the bootstrapper loads ocelot.json automatically; no manual configuration setup required
• Indiko Blocks — extend the gateway with auth, rate-limiting, tracing, or custom blocks participating in the full host lifecycle
• Flexible host builder — ConfigureHostBuilder(...) fluent API for Windows Service, systemd, and custom configurations
• Options-driven or property-override configuration — toggle features via appsettings.json or subclass property overrides

Installation

dotnet add package Indiko.Hosting.Gateway

Quick Start

1. Create your Startup class

using Indiko.Hosting.Gateway;

public class Startup : GatewayStartup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment environment)
        : base(configuration, environment)
    {
    }

    // Optional: add custom services before Ocelot runs
    public override void ConfigureServices(IServiceCollection services)
    {
        base.ConfigureServices(services);
        services.AddSingleton<IMyGatewayService, MyGatewayService>();
    }
}

2. Write Program.cs

// Program.cs
return await new GatewayHostBootstrapper()
    .RunAsync<Startup>(args);

3. Configure appsettings.json

{
  "ServiceName": "MyGateway",
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Ocelot": "Information"
    }
  },
  "GatewayStartupOptions": {
    "EnableForwardedHeaderOptions": true,
    "ForceHttps": false
  }
}

4. Create ocelot.json

Place ocelot.json in your project root. It is loaded automatically by GatewayHostBootstrapper.

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [{ "Host": "user-service", "Port": 80 }],
      "UpstreamPathTemplate": "/users/{everything}",
      "UpstreamHttpMethod": ["GET", "POST", "PUT", "DELETE"]
    }
  ],
  "GlobalConfiguration": {
    "ServiceDiscoveryProvider": {
      "Scheme": "http",
      "Host": "consul",
      "Port": 8500,
      "Type": "Consul"
    }
  }
}

5. Run

dotnet run

Configuration Approaches

Approach A: appsettings.json (recommended)

{
  "GatewayStartupOptions": {
    "EnableForwardedHeaderOptions": true,
    "ForceHttps": false,
    "AddControllersWithViews": false
  }
}

All properties default to false when the section is absent.

Approach B: Property overrides in code

public class Startup : GatewayStartup
{
    public Startup(IConfiguration configuration, IWebHostEnvironment environment)
        : base(configuration, environment)
    {
    }

    protected override bool EnableForwardedHeaderOptions => true;
    protected override bool ForceHttps                  => false;
    protected override bool AddControllersWithViews      => false;
}

Precedence: Subclass property overrides always win over appsettings.json values.

Startup Options Reference

EnableForwardedHeaderOptions and ForceHttps are inherited from HostStartupOptions (defined in Indiko.Hosting.Abstractions). AddControllersWithViews is declared in GatewayStartupOptions for subclasses that need MVC controllers alongside the gateway.

Flexible Host Builder

Because GatewayHostBootstrapper is sealed, use the ConfigureHostBuilder fluent API:

// Windows Service
return await new GatewayHostBootstrapper()
    .ConfigureHostBuilder(b => b.UseWindowsService())
    .RunAsync<Startup>(args);

// systemd (Linux)
return await new GatewayHostBootstrapper()
    .ConfigureHostBuilder(b => b.UseSystemd())
    .RunAsync<Startup>(args);

// Custom Kestrel port
return await new GatewayHostBootstrapper()
    .ConfigureHostBuilder(b => b.ConfigureWebHostDefaults(web =>
        web.ConfigureKestrel(k => k.ListenAnyIP(8080))))
    .RunAsync<Startup>(args);

// Chain multiple actions
return await new GatewayHostBootstrapper()
    .ConfigureHostBuilder(b => b.UseWindowsService())
    .ConfigureHostBuilder(b => b.ConfigureLogging(l => l.AddConsole()))
    .RunAsync<Startup>(args);

ocelot.json

The GatewayHostBootstrapper calls config.AddJsonFile("ocelot.json") automatically during host construction. The file must exist in the application's working directory.

Basic route

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/{everything}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        { "Host": "user-service", "Port": 80 }
      ],
      "UpstreamPathTemplate": "/users/{everything}",
      "UpstreamHttpMethod": ["GET", "POST", "PUT", "DELETE"]
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "https://api.example.com"
  }
}

With Consul service discovery and load balancing

{
  "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"
    }
  }
}

Consul Service Discovery

The bootstrapper calls services.AddOcelot(Configuration).AddConsul(), which registers the Consul service discovery provider. The provider is activated when GlobalConfiguration.ServiceDiscoveryProvider.Type is "Consul" in ocelot.json.

Routes use "ServiceName" instead of "DownstreamHostAndPorts" when discovery is active:

{
  "ServiceName": "product-service",
  "LoadBalancerOptions": { "Type": "RoundRobin" }
}

Consul resolves registered instances of product-service and the load balancer selects among them. Health-checked instances that fail are automatically removed.

Forwarded Headers

The Gateway package uses a stricter forwarded headers configuration than the BlazorServer package. When EnableForwardedHeaderOptions = true:

var options = new ForwardedHeadersOptions
{
    ForwardedHeaders = ForwardedHeaders.All
};
options.KnownNetworks.Clear();
options.KnownProxies.Clear();
app.UseForwardedHeaders(options);

KnownNetworks and KnownProxies are cleared so that forwarded headers from any upstream proxy are trusted. This is appropriate for gateway deployments behind an internal load balancer or Kubernetes ingress where the proxy IP is not fixed.

Do not enable this on internet-facing applications without a trusted proxy — it would allow clients to spoof their IP address via X-Forwarded-For.

Extending with Indiko Blocks

Blocks hook into the gateway lifecycle at every stage:

Example: adding an authentication block and a rate-limiting block:

// The blocks register themselves via Indiko block discovery.
// In appsettings.json, reference the block assemblies:
{
  "Blocks": [
    "Indiko.Blocks.Security.Authentication.ASPNetCore",
    "Indiko.Blocks.RateLimiting"
  ]
}

Best Practices

• Always set EnableForwardedHeaderOptions = true when the gateway runs behind a Kubernetes ingress, nginx, or any other reverse proxy.
• Use Consul service discovery with health checks rather than hardcoded DownstreamHostAndPorts in production.
• Set ForceHttps = false when TLS terminates at the ingress layer; enable it only when the gateway itself terminates TLS.
• Separate ocelot.json per environment using Ocelot's environment-specific file convention: ocelot.Development.json, ocelot.Production.json. Load them alongside ocelot.json in a ConfigureHostBuilder action.
• Keep the ConfigureServices and Configure overrides minimal — delegate cross-cutting concerns (auth, rate limiting, tracing) to Indiko Blocks.

Target Framework

.NET 10

License

MIT — see LICENSE in the repository root.

Related Packages

Resources

• Ocelot Documentation
• Consul Documentation