rl-nginx

rl-nginx documentation

rl-nginx connects nginx’s HTTP request lifecycle to RateLimitly through the public C client. The documentation is layered so readers can learn the model before dealing with build, configuration, or operational details.

Start here

1. Read the README’s operation model and small nginx examples.
2. Build a supported static or dynamic module with Building and installing rl-nginx.
3. Turn application policy into nginx directives with Configuring rl-nginx.
4. Before production, read Operating rl-nginx and the Compatibility and release scope.

Copyable configurations are in examples/. Start with minimal.conf; use security-conscious.conf for bounded identity maps, dynamic rates, labels, and latency guards.

Find a topic

Goal	Document
Build or package the module	Build and installation
Configure resources, groups, guards, credentials, and failure policy	Configuration guide
Plan DNS, rollout, logging, recovery, and troubleshooting	Operations guide
Check supported nginx/client versions and release gates	Compatibility guide
Understand the nginx/C-client ownership and callback boundary	C-client integration
Look up exact directive or observable behavior	Normative specification
Run or extend the public lifecycle fixtures	Integration-test guide

Documentation ownership

This repository is authoritative for behavior added by the nginx module:

• directive syntax, scope, inheritance, and rendered nginx values;
• final pre-content admission ordering and internal-redirect behavior;
• fail-open/fail-close mapping and $ratelimitly_verdict;
• nginx request, timer, resolver, socket, reload, and cleanup lifetimes; and
• the module’s admission-aware HTTP latency measurement.

The locked rl-c-client v1.0.0 documentation is authoritative for behavior owned by the client:

• resource requests and independent latency reports;
• credentials and API-key quotas;
• content-defined bucket and latency-tracker IDs;
• resource-request HA policy and deduplication TTL;
• DNS refresh; and
• client error codes.

Links deliberately target the supported tag rather than main. The exact tag and commit are locked in dependencies/rl-c-client.env. Updating the lock requires reviewing these links, the nginx-specific summaries, and the executable compatibility contract together.

Project policies and history

• SUPPORT.md — support scope and issue-report checklist.
• SECURITY.md — private vulnerability reporting.
• CODE_OF_CONDUCT.md — community standards.
• CHANGELOG.md — release status and notable changes.
• THIRD_PARTY_NOTICES.md — dependency licenses.

This site is open source. Improve this page.