|
| 1 | += Rate Limiting Requests |
| 2 | +ifndef::env-site,env-github[] |
| 3 | +include::_attributes.adoc[] |
| 4 | +endif::[] |
| 5 | +:imagesdir: ../assets/images |
| 6 | + |
| 7 | +Flex Gateway Policy Development Kit (PDK) provides rate limiting functionality to control request rates. |
| 8 | + |
| 9 | +Custom policies support both single Flex Replica and multi-replica deployments. For multi-replica deployments, you must configure shared storage. To configure shared storage, see: |
| 10 | + |
| 11 | +* xref:gateway::flex-conn-shared-storage-config.adoc[] |
| 12 | +* xref:gateway::flex-local-shared-storage-config.adoc[] |
| 13 | +
|
| 14 | +== Inject the `RateLimitBuilder` |
| 15 | + |
| 16 | +To enable rate limiting functionality, you need to inject the `RateLimitBuilder` in your custom policy's entrypoint and configure it for either local (single-replica) or clustered (multi-replica) mode: |
| 17 | + |
| 18 | +[source,Rust] |
| 19 | +---- |
| 20 | +// buckets example configuration |
| 21 | +let buckets = vec![ |
| 22 | + ("api", vec![Tier { requests: 100, period_in_millis: 60000 }]), // 100 requests per minute |
| 23 | + ("user", vec![Tier { requests: 10, period_in_millis: 30000 }]), // 10 requests per 30 seconds |
| 24 | +]; |
| 25 | +
|
| 26 | +// timer example |
| 27 | +let timer = clock.period(Duration::from_millis(100)); // 100ms intervals for rate limit sync |
| 28 | +
|
| 29 | +// for local mode (single-instance) |
| 30 | +let builder = rate_limit_builder |
| 31 | + .new(builder_id); |
| 32 | +let rate_limiter = builder.buckets(buckets).build()?; |
| 33 | +
|
| 34 | +// for clustered mode with shared storage (multi-instance) |
| 35 | +let builder = rate_limit_builder |
| 36 | + .new(builder_id) |
| 37 | + .clustered(Rc::new(timer)) |
| 38 | + .shared(); |
| 39 | +let rate_limiter = builder.buckets(buckets).build()?; |
| 40 | +---- |
| 41 | + |
| 42 | +The `RateLimitBuilder` struct provides the following methods to configure the rate limits: |
| 43 | + |
| 44 | +* `builder_id`: a string identifier for the rate limiter instance (required) |
| 45 | +* `buckets`: rate limit tiers configuration with requests and time windows (optional - defaults to api instance configuration if unspecified) |
| 46 | +* `timer`: a periodic timer for rate limit sync (required for clustered mode) |
| 47 | +* `clustered`: Enables the rate limiter to use distributed storage backends. Without it, the rate limiter uses in-memory storage. |
| 48 | +* `shared`: Enables the rate limiter to share state across different policy instances. |
| 49 | + |
| 50 | +== Check Requests Against Rate Limits |
| 51 | + |
| 52 | +After creating the rate limiter instance, use the `is_allowed` method to check if requests are allowed with support for multiple independent rate limit configurations: |
| 53 | + |
| 54 | +[source,Rust] |
| 55 | +---- |
| 56 | +// Check if request is allowed for a specific group and client key |
| 57 | +match rate_limiter.is_allowed(group, &client_key, request_amount).await { |
| 58 | + Ok(RateLimitResult::Allowed(_)) => Flow::Continue(()), |
| 59 | + Ok(RateLimitResult::TooManyRequests(_)) => Flow::Break(Response::new(429)), |
| 60 | + Err(e) => Flow::Break(Response::new(503)), |
| 61 | +} |
| 62 | +---- |
| 63 | + |
| 64 | +== Rate Limiting Configuration Examples |
| 65 | + |
| 66 | +PDK provides the https://github.com/mulesoft/pdk-custom-policy-examples/tree/{template-policies-url-ver-var}/multi-instance-rate-limiting[Multi-Instance Rate Limiting Example policy] to demonstrate how to configure rate limiting in Rust code. |
| 67 | + |
| 68 | +Within the example policy, see these functions for further configuration details: |
| 69 | + |
| 70 | +* https://github.com/mulesoft/pdk-custom-policy-examples/tree/{template-policies-url-ver-var}/multi-instance-rate-limiting/src/lib.rs#L118[`entrypoint` function] for how to configure the `RateLimitBuilder`. |
| 71 | + |
| 72 | +* https://github.com/mulesoft/pdk-custom-policy-examples/tree/{template-policies-url-ver-var}/multi-instance-rate-limiting/src/lib.rs#L54[`request_filter` function] for how the policy applies rate limits to incoming requests. |
| 73 | + |
| 74 | +== Redis Shared Storage Configuration Example |
| 75 | + |
| 76 | +For an example of how to configure Redis shared storage for testing, see the example https://github.com/mulesoft/pdk-custom-policy-examples/blob/{template-policies-url-ver-var}/multi-instance-rate-limiting/playground/docker-compose.yaml[`playground/docker-compose.yaml`] file. |
| 77 | + |
| 78 | + |
| 79 | + |
| 80 | +== See Also |
| 81 | + |
| 82 | +* xref:policies-pdk-configure-features-timer.adoc[] |
| 83 | +* xref:policies-pdk-configure-features-share-data.adoc[] |
0 commit comments