Kong / Kong/docs.konghq.com

The Rate Limiting Advanced plugin documentation could use some extra details around types of identifiers

Open
#4,156 0 comments 0 reactions 0 assignees View on GitHub
papercut
Dominant language
Ruby
Stars
212
Forks
587
PR merge metrics
No merged PRs in 30d

Description

### Where is the problem?

https://docs.konghq.com/hub/kong-inc/rate-limiting-advanced/#parameters

### What happened?

A support case was opened asking for clarification on how 'header' and 'credential' identifier types are handled in the Rate Limiting plugins, as our documentation doesn't quite make that clear at this time. Their specific questions are below for context:

_1. If we set "config.limit_by = header" and "config.header_name = x-rate-limit-header", and two requests arrive with "x-rate-limit-header = one" and "x-rate-limit-header = two" respectively, will the two requests be aggregated into different counters? In other words, do different header values identify different counters?
2. If we set "config.limit_by = credential", what happens? There's no explanation whatsoever of what credential refers to, nor what the expected behavior is._

### What did you expect to happen?

I think these questions from one of our customers brings up a good use-case to improving our documentation on the Rate Limiting plugins with regards to how the different identifiers work exactly (especially the ones without a related sub-parameter).

FWIW (and someone else may have a better explanation than mine), I believe those two identifiers in particular can be explained in a manner similar to this:

- 'credential' type is handled automatically (no sub-parameter involved) and incremented on each set of credentials seen in any Auth-related plugin (i.e. OIDC, LDAP, Key-Auth, etc)
- 'header' type requires the use of the 'header_name' parameter, and it increments on the keypair of header name and header value. If a header name is used but seen with multiple different values, they only increment as one until a matching keypair has been seen.

### Code of Conduct and Community Expectations

- [X] I agree to follow this project's Code of Conduct
- [X] I agree to abide by the Community Expectations

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the Rate Limiting Advanced documentation's parameters section at the linked page, then check the current documentation site because this repository is archived. Clarify the handling of header and credential identifiers, and consider the work done when both behaviors and their relevant configuration are explicitly explained.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.