1.0.3 • Published yesterday

sla-wizard-plugin-auth-request-ratelimit

Licence

—

Version

1.0.3

Deps

Size

126 kB

Vulns

Weekly

Summary Dependency Versions

sla-wizard-plugin-auth-request-ratelimit

A sla-wizard plugin that augments nginx's static limit_req rate limiting with a dynamic auth_request-based delegation to alma-telemeter.

When alma-telemeter is reachable, every request passes through a subrequest that enforces the rate limit and returns live X-RateLimit-* headers. When alma-telemeter is unreachable, nginx falls back to its own limit_req token-bucket limiter so SLA limits are always enforced.

How it fits in the plugin chain

configNginxAuthRequest
  └─ sla-wizard-plugin-custom-baseurl  (configNginxBaseUrl)
       └─ sla-wizard-plugin-nginx-strip  (configNginxStrip)
            └─ sla-wizard-nginx-confd  (configNginxConfd)

Architecture: dual-layer rate limiting

The plugin deliberately keeps both limiters active at all times:

Client request
  │
  ├─ [nginx preaccess] limit_req zone=… burst=N nodelay
  │     token-bucket guard; burst = SLA_max − 1
  │     → 429 @rate_limited_static (if burst exhausted)
  │
  ├─ [nginx rewrite]  set $rl_limit_static N+1
  │
  └─ [nginx access]   auth_request /internal/rate-limit-check
        │
        ├─ Telemeter UP → 200 (allowed) or 403 (exceeded)
        │     200 → forward upstream + dynamic X-RateLimit-* headers
        │     403 → error_page 403 =429 @rate_limited (dynamic headers)
        │
        └─ Telemeter DOWN (5xx / timeout)
              → /_telemeter_down returns 200
              → request allowed through; limit_req already ran above
              → static X-RateLimit-* headers from map fallback

Path summary

Scenario	Enforcer	Rate-limit headers
Telemeter UP, within limit	telemeter (fixed-window Redis)	Dynamic from telemeter
Telemeter UP, limit exceeded	telemeter → `@rate_limited`	Dynamic from telemeter
Telemeter DOWN, within burst	`limit_req` (token-bucket)	Static (`$rl_limit_static`)
Telemeter DOWN, burst exceeded	`limit_req` → `@rate_limited_static`	Static, partial
Redis DOWN	telemeter fail-open → `limit_req`	Static (`$rl_limit_static`)

Installation

npm install sla-wizard-plugin-auth-request-ratelimit

Runtime dependency

alma-telemeter must be reachable from nginx. It receives subrequests at /internal/rate-limit and responds with X-RateLimit-* headers.

Default endpoint: http://127.0.0.1:2047/internal/rate-limit. Override with --telemeterUrl CLI option or TELEMETER_URL environment variable.

CLI usage

// cli.js
const slaWizard = require('sla-wizard');
const authRequestPlugin = require('sla-wizard-plugin-auth-request-ratelimit');

slaWizard.use(authRequestPlugin);
slaWizard.program.parse(process.argv);

node cli.js --help

`config-nginx-auth-request`

Generates a full nginx configuration (nginx.conf + conf.d/) with auth_request-based rate limiting applied.

node cli.js config-nginx-auth-request \
  -o <outputDirectory> \
  --oas <pathToOAS>                   \  # default: ./specs/oas.yaml
  --sla <slaFileOrDirectory>          \  # default: ./specs/sla.yaml
  --authLocation <header|query|url>   \  # default: header
  --authName <paramName>              \  # default: apikey
  --proxyPort <port>                  \  # default: 80
  --telemeterUrl <url>                \  # default: http://127.0.0.1:2047/internal/rate-limit
  [--customTemplate <file>]

`add-to-auth-request-confd`

Generates only conf.d/ files for a new user without touching nginx.conf. Use when nginx.conf was already generated by a previous config-nginx-auth-request run.

node cli.js add-to-auth-request-confd \
  -o <outputDirectory> \
  --oas <pathToOAS> \
  --sla <slaFileOrDirectory>

Programmatic usage

const slaWizard = require('sla-wizard');
const authRequestPlugin = require('sla-wizard-plugin-auth-request-ratelimit');

slaWizard.use(authRequestPlugin);

// Full config (nginx.conf + conf.d/)
slaWizard.configNginxAuthRequest({
  outDir:       './nginx-output',
  oas:          './specs/oas.yaml',
  sla:          './specs/slas',
  telemeterUrl: 'http://telemeter-host:2047/internal/rate-limit', // optional
});

// conf.d only (nginx.conf already exists)
slaWizard.addToAuthRequestConfd({
  outDir: './nginx-output',
  oas:    './specs/oas.yaml',
  sla:    './specs/slas/new-user.yaml',
});

Direct import

const {
  DEFAULT_TELEMETER_URL,
  applyAuthRequestToConfd,                   // (content: string) → string
  applyAuthRequestToNginxConf,               // (content: string, telemeterUrl?: string) → string
  applyAuthRequestTransformations,           // (outDir: string,  telemeterUrl?: string) → void
  applyAuthRequestTransformationsConfdOnly,  // (outDir: string) → void
} = require('sla-wizard-plugin-auth-request-ratelimit');

const transformed = applyAuthRequestToConfd(fs.readFileSync('user.conf', 'utf8'));
applyAuthRequestTransformations('./nginx-output', 'http://telemeter-host:2047/internal/rate-limit');

nginx transformations applied

`nginx.conf` changes

Element	After transformation
`limit_req_zone …`	(kept — nginx-native fallback when telemeter is down)
`limit_req_status 429;`	(kept — fallback)
Before `server {`	Two `map` directives injected (header fallback logic)
Before `include conf.d/*.conf;`	`location /internal/rate-limit-check` injected
Before `include conf.d/*.conf;`	`location = /_telemeter_down` injected
Before `include conf.d/*.conf;`	`location @rate_limited` injected
Before `include conf.d/*.conf;`	`location @rate_limited_static` injected

Injected map directives (http context, before server {):

map $rl_limit $rl_limit_header {
    ""      $rl_limit_static;   # telemeter down or Redis fail-open → static value
    default $rl_limit;          # telemeter up → dynamic value
}

map $rl_remaining $rl_remaining_header {
    ""      -1;                 # telemeter down → -1 signals unavailable
    default $rl_remaining;      # telemeter up → dynamic value
}

Injected /internal/rate-limit-check block:

location /internal/rate-limit-check {
    internal;
    proxy_pass              http://127.0.0.1:2047/internal/rate-limit;
    proxy_pass_request_body off;
    proxy_set_header        X-API-Key  $http_apikey;
    proxy_set_header        X-Endpoint $uri_original;
    proxy_set_header        X-Method   $request_method;
    proxy_connect_timeout   500ms;
    proxy_read_timeout      1s;
    proxy_intercept_errors  on;
    error_page 500 502 503 504 =200 /_telemeter_down;
}

Injected /_telemeter_down block (telemeter unreachable → allow through, fall back to limit_req):

location = /_telemeter_down {
    internal;
    return 200;
}

Injected @rate_limited block (telemeter rejected the request → dynamic 429):

location @rate_limited {
    default_type application/json;
    add_header X-RateLimit-Limit     $rl_limit always;
    add_header X-RateLimit-Remaining 0         always;
    add_header X-RateLimit-Reset     $rl_reset always;
    add_header Retry-After           $rl_retry always;
    return 429 '{"error":"TooManyRequests","message":"Rate limit exceeded","status":429}';
}

Injected @rate_limited_static block (limit_req rejected the request → static 429):

location @rate_limited_static {
    default_type application/json;
    add_header X-RateLimit-Remaining 0   always;
    add_header Retry-After           60  always;
    return 429 '{"error":"TooManyRequests","message":"Rate limit exceeded","status":429}';
}

`conf.d/*.conf` changes (per rate-limited location block)

The original limit_req line is kept as the first directive (nginx-native fallback). The auth_request block is injected immediately after it.

Before:

location /sla-user1_endpoint_POST {
    rewrite … break;
    proxy_pass http://localhost:8000;
    limit_req zone=sla-user1_endpoint_POST burst=4 nodelay;
}

After:

location /sla-user1_endpoint_POST {
    rewrite … break;
    proxy_pass http://localhost:8000;
    limit_req zone=sla-user1_endpoint_POST burst=4 nodelay;   # kept as fallback

    set $rl_limit_static          5;   # burst+1 = SLA max; static header fallback
    auth_request      /internal/rate-limit-check;
    auth_request_set  $rl_limit     $upstream_http_x_ratelimit_limit;
    auth_request_set  $rl_remaining $upstream_http_x_ratelimit_remaining;
    auth_request_set  $rl_reset     $upstream_http_x_ratelimit_reset;
    auth_request_set  $rl_retry     $upstream_http_retry_after;

    add_header X-RateLimit-Limit     $rl_limit_header     always;
    add_header X-RateLimit-Remaining $rl_remaining_header always;
    add_header X-RateLimit-Reset     $rl_reset            always;

    error_page 403 =429 @rate_limited;
    error_page 429      @rate_limited_static;
}

$rl_limit_header and $rl_remaining_header resolve via the map directives in nginx.conf:

Telemeter UP: take dynamic values from telemeter response headers.
Telemeter DOWN: $rl_limit_header → $rl_limit_static; $rl_remaining_header → -1.

Response headers

On successful (2xx) responses

Telemeter state	Header	Value
UP	`X-RateLimit-Limit`	Dynamic — SLA max from telemeter
UP	`X-RateLimit-Remaining`	Dynamic — requests left in current window
UP	`X-RateLimit-Reset`	Dynamic — Unix timestamp of window reset
DOWN	`X-RateLimit-Limit`	Static — `$rl_limit_static` (SLA burst + 1)
DOWN	`X-RateLimit-Remaining`	`-1` (sentinel: telemeter unavailable)
DOWN	`X-RateLimit-Reset`	(absent — `limit_req` does not expose window time)

On rate-limited (429) responses

Via @rate_limited (telemeter rejected the request):

Header	Value
`X-RateLimit-Limit`	Dynamic — SLA max
`X-RateLimit-Remaining`	`0`
`X-RateLimit-Reset`	Dynamic — Unix timestamp of window reset
`Retry-After`	Dynamic — seconds until window resets

Via @rate_limited_static (limit_req burst exhausted before auth_request ran):

Header	Value
`X-RateLimit-Remaining`	`0`
`Retry-After`	`60` (conservative hardcoded fallback)
`X-RateLimit-Limit`	(absent — `set $rl_limit_static` runs in rewrite phase, after `limit_req` preaccess rejection)
`X-RateLimit-Reset`	(absent — `limit_req` does not expose window time)

Response body (both 429 paths):

{"error":"TooManyRequests","message":"Rate limit exceeded","status":429}

Headers not added

Responses rejected before any location block runs — 401 Unauthorized (missing API key) and 403 Forbidden (unknown API key) — do not carry X-RateLimit-* headers because the auth_request subrequest never fires for those requests.

Exported API reference

Export	Signature	Description
`apply`	`(program, ctx) → void`	sla-wizard plugin entry point
`DEFAULT_TELEMETER_URL`	`string`	`http://127.0.0.1:2047/internal/rate-limit`
`configNginxAuthRequest`	`(options, ctx) → void`	Full config generation (nginx.conf + conf.d/)
`addToAuthRequestConfd`	`(options, ctx) → void`	conf.d-only generation
`applyAuthRequestToConfd`	`(content: string) → string`	Transforms one conf.d file content
`applyAuthRequestToNginxConf`	`(content: string, telemeterUrl?: string) → string`	Transforms nginx.conf content
`applyAuthRequestTransformations`	`(outDir: string, telemeterUrl?: string) → void`	Transforms all files in outDir
`applyAuthRequestTransformationsConfdOnly`	`(outDir: string) → void`	Transforms only conf.d/ files

Testing

# Unit tests + container integration tests (requires Docker)
npm test

# Unit tests only (no Docker required)
npx mocha ./tests/tests.js

Test suite overview

Suite	Tests	Type
`applyAuthRequestToConfd`	17	Unit (pure string)
`applyAuthRequestToNginxConf`	17	Unit (pure string)
`applyAuthRequestTransformations`	6	Unit (filesystem)
`applyAuthRequestTransformationsConfdOnly`	4	Unit (filesystem)
Module shape + plugin registration	9	Unit
`configNginxAuthRequest` programmatic	23	Integration
`addToAuthRequestConfd` programmatic	6	Integration
CLI usage	10	CLI (`execSync`)
Container: X-RateLimit headers under limit	8	Container (Docker)
Container: 429 with correct headers	6	Container (Docker)
Container: independent counters per key	3	Container (Docker)
Container: authentication checks	2	Container (Docker)
Total	111

The container tests spin up three Docker containers (echo backend, mock alma-telemeter, nginx with the generated config) and verify the full request cycle end-to-end, including live header values and rate-limit enforcement.