RateLimiter.IISModule 1.0.5

IIS Rate Limiter Module

A custom IIS HTTP Module for subsystem-wise and API-wise rate limiting. Perfect for APIs that use custom authentication headers to identify clients/subsystems.

Features

• Subsystem-based rate limiting - Different limits per client/subsystem from Authorization header
• Per-endpoint rate limiting - Different limits for different URLs
• URL pattern matching - Wildcards support (* for segment, ** for any path)
• HTTP method filtering - Different limits for GET vs POST
• Hierarchical rules - Subsystem-specific → Global API rules → Default limits
• Hot reload - Configuration changes apply without IIS restart
• Sliding window algorithm - Smooth rate limiting without sharp resets
• Configurable via JSON - Easy configuration without code changes

Installation

Option 1: NuGet Package

Install-Package RateLimiter.IISModule

Option 2: Manual Installation

1. Build the Module

cd RateLimiter.IISModule
dotnet build -c Release

2. Deploy to Your Web Application

Copy the built DLLs to your application's bin folder:

copy .\bin\Release\net48\RateLimiter.IISModule.dll C:\inetpub\wwwroot\YourAppName\bin\
copy .\bin\Release\net48\Newtonsoft.Json.dll C:\inetpub\wwwroot\YourAppName\bin\

Modules

This package includes two rate limiting modules:

SubsystemRateLimitingModule

Rate limits based on subsystem name extracted from Authorization header.

Authorization Header Format

Authorization: amx {token}:{signature}:{id}:{SUBSYSTEM}:{timestamp}

Example:

Authorization: amx 4e0e3de0-dde3-4d8b-a291-365d31099e80:syZZECkt...:905b3781...:T-SystemsDevelopment:1767956650

The module extracts T-SystemsDevelopment as the subsystem.

Setup

1. Register in web.config

<configuration>
  <system.webServer>
    <modules>
      <add name="SubsystemRateLimitingModule" 
           type="RateLimiter.IISModule.SubsystemRateLimitingModule, RateLimiter.IISModule" 
           preCondition="managedHandler" />
    </modules>
  </system.webServer>
</configuration>

2. Create Configuration

Create App_Data\ratelimit.subsystem.config.json:

{
  "enabled": true,
  "applicationPathPrefix": "",
  
  "defaultLimit": {
    "maxRequests": 100,
    "windowSeconds": 60
  },
  
  "globalApiRules": [
    {
      "name": "Invoice API",
      "urlPattern": "/api/v3/external/service/invoice",
      "methods": ["GET"],
      "maxRequests": 50,
      "windowSeconds": 60,
      "priority": 100
    }
  ],
  
  "subsystemRules": {
    "PremiumClient": {
      "defaultLimit": {
        "maxRequests": 200,
        "windowSeconds": 60
      },
      "apiRules": [
        {
          "name": "PremiumClient Invoice",
          "urlPattern": "/api/v3/external/service/invoice",
          "maxRequests": 100,
          "windowSeconds": 60
        }
      ]
    },
    "BasicClient": {
      "defaultLimit": {
        "maxRequests": 50,
        "windowSeconds": 60
      }
    }
  },
  
  "whitelistedSubsystems": ["InternalMonitoring"],
  "excludedPaths": ["/health", "/api/health"]
}

Rate Limit Hierarchy

The rate limiter applies limits in this order (first match wins):

1. Subsystem-specific API rule (e.g., PremiumClient + Invoice API)
2. Subsystem default limit (e.g., PremiumClient default)
3. Global API rule (e.g., Invoice API for all subsystems)
4. Global default limit (fallback)

Subsystem Configuration Options

RateLimitingModule

General-purpose rate limiting by IP, API key, or custom headers.

Setup

1. Register in web.config

<configuration>
  <system.webServer>
    <modules>
      <add name="RateLimitingModule" 
           type="RateLimiter.IISModule.RateLimitingModule, RateLimiter.IISModule" 
           preCondition="managedHandler" />
    </modules>
  </system.webServer>
</configuration>

2. Create Configuration

Create App_Data\ratelimit.config.json:

{
  "includeUrlInKey": true,
  "includeMethodInKey": true,
  "clientIdHeader": "X-API-Key",
  
  "defaultRule": {
    "name": "Default",
    "maxRequests": 100,
    "windowSeconds": 60
  },
  
  "rules": [
    {
      "name": "Login",
      "urlPattern": "/api/auth/login",
      "methods": ["POST"],
      "maxRequests": 5,
      "windowSeconds": 60,
      "priority": 100
    }
  ]
}

General Configuration Options

Common Configuration

Rate Limit Rule Properties

URL Pattern Examples

Response When Rate Limited

HTTP Status: 429 Too Many Requests

Headers:

Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Window: 60s

Body (SubsystemRateLimitingModule):

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded for subsystem 'BasicClient' on API '/api/v3/external/service/invoice'.",
  "details": {
    "subsystem": "BasicClient",
    "api": "/api/v3/external/service/invoice",
    "limit": 50,
    "windowSeconds": 60,
    "retryAfter": 60
  }
}

Hot Reload

Configuration files are automatically reloaded when modified. No IIS restart required for configuration changes!

Troubleshooting

Module Not Loading

1. Ensure .NET Framework 4.8 is installed
2. Check Application Pool uses .NET 4.0 CLR (Integrated mode)
3. Verify DLLs are in the bin folder

Rate Limits Not Applied

1. Check the module is registered in web.config
2. Verify config file is in App_Data folder
3. Check URL patterns match your endpoints
4. Check if subsystem/IP is whitelisted

Wrong Subsystem Detected

1. Verify Authorization header format: amx {token}:{signature}:{id}:{subsystem}:{timestamp}
2. The subsystem is the 4th colon-separated value

Performance Considerations

• In-memory sliding window algorithm (fast)
• Automatic cleanup of expired entries
• Thread-safe concurrent dictionary
• Minimal overhead (~1ms per request)
• For web farm scenarios, consider Redis-based implementation

License

MIT License