diff --git a/pdk/1.5/modules/ROOT/nav.adoc b/pdk/1.5/modules/ROOT/nav.adoc index 4a252484c..4a7c18abc 100644 --- a/pdk/1.5/modules/ROOT/nav.adoc +++ b/pdk/1.5/modules/ROOT/nav.adoc @@ -20,6 +20,7 @@ *** xref:policies-pdk-configure-features-libraries.adoc[] *** xref:policies-pdk-configure-features-caching.adoc[] *** xref:policies-pdk-configure-features-metadata.adoc[] +*** xref:policies-pdk-configure-features-rate-limiting.adoc[] *** xref:policies-pdk-configure-features-streamproperties.adoc[] *** xref:policies-pdk-configure-features-authentication.adoc[] *** xref:policies-pdk-configure-features-timer.adoc[] diff --git a/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-inject-parameters.adoc b/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-inject-parameters.adoc index bc421cf2d..4b7958c14 100644 --- a/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-inject-parameters.adoc +++ b/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-inject-parameters.adoc @@ -12,6 +12,7 @@ Flex Gateway Policy Development Kit (PDK) provides the following parameters that * `CacheBuilder`: Provides the caching features of the policy. For more information about caching, see xref:policies-pdk-configure-features-caching.adoc[]. * `StreamProperties`: Provides a structure to share properties with other policies that process the same request. For more information about sharing information between policies, see xref:policies-pdk-configure-features-streamproperties.adoc[]. * `PolicyViolations``: Provides a mechanism to report policy violations for your monitoring dashboards. For more information about policy violations, see xref:policies-pdk-configure-features-violations.adoc[]. +* `RateLimitBuilder`: Provides rate limiting functionality to control request rates. For more information about rate limiting, see xref:policies-pdk-configure-features-rate-limiting.adoc[]. You can also directly inject the `HttpClient` and `StreamProperties` parameter into the `on_request` or `on_response` wrapped functions. For example, if you need to perform an HTTP call inside the `on_request` function, inject `HTTPClient` directly into that function. diff --git a/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-rate-limiting.adoc b/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-rate-limiting.adoc new file mode 100644 index 000000000..86abac05b --- /dev/null +++ b/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-rate-limiting.adoc @@ -0,0 +1,83 @@ += Rate Limiting Requests +ifndef::env-site,env-github[] +include::_attributes.adoc[] +endif::[] +:imagesdir: ../assets/images + +Flex Gateway Policy Development Kit (PDK) provides rate limiting functionality to control request rates. + +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: + +* xref:gateway::flex-conn-shared-storage-config.adoc[] +* xref:gateway::flex-local-shared-storage-config.adoc[] + +== Inject the `RateLimitBuilder` + +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: + +[source,Rust] +---- +// buckets example configuration +let buckets = vec![ + ("api", vec![Tier { requests: 100, period_in_millis: 60000 }]), // 100 requests per minute + ("user", vec![Tier { requests: 10, period_in_millis: 30000 }]), // 10 requests per 30 seconds +]; + +// timer example +let timer = clock.period(Duration::from_millis(100)); // 100ms intervals for rate limit sync + +// for local mode (single-instance) +let builder = rate_limit_builder + .new(builder_id); +let rate_limiter = builder.buckets(buckets).build()?; + +// for clustered mode with shared storage (multi-instance) +let builder = rate_limit_builder + .new(builder_id) + .clustered(Rc::new(timer)) + .shared(); +let rate_limiter = builder.buckets(buckets).build()?; +---- + +The `RateLimitBuilder` struct provides the following methods to configure the rate limits: + +* `builder_id`: a string identifier for the rate limiter instance (required) +* `buckets`: rate limit tiers configuration with requests and time windows (optional - defaults to api instance configuration if unspecified) +* `timer`: a periodic timer for rate limit sync (required for clustered mode) +* `clustered`: Enables the rate limiter to use distributed storage backends. Without it, the rate limiter uses in-memory storage. +* `shared`: Enables the rate limiter to share state across different policy instances. + +== Check Requests Against Rate Limits + +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: + +[source,Rust] +---- +// Check if request is allowed for a specific group and client key +match rate_limiter.is_allowed(group, &client_key, request_amount).await { + Ok(RateLimitResult::Allowed(_)) => Flow::Continue(()), + Ok(RateLimitResult::TooManyRequests(_)) => Flow::Break(Response::new(429)), + Err(e) => Flow::Break(Response::new(503)), +} +---- + +== Rate Limiting Configuration Examples + +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. + +Within the example policy, see these functions for further configuration details: + +* 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`. + +* 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. + +== Redis Shared Storage Configuration Example + +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. + + + +== See Also + +* xref:policies-pdk-configure-features-timer.adoc[] +* xref:policies-pdk-configure-features-share-data.adoc[] diff --git a/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-share-data.adoc b/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-share-data.adoc index 94e7eba61..97408d6d5 100644 --- a/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-share-data.adoc +++ b/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-share-data.adoc @@ -51,3 +51,4 @@ async fn response_filter(state: ResponseState, request_data: RequestData == See Also * xref:policies-pdk-configure-features.adoc[] +* xref:policies-pdk-configure-features-rate-limiting.adoc[] diff --git a/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-timer.adoc b/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-timer.adoc index 203e367f1..a10e2fa67 100644 --- a/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-timer.adoc +++ b/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features-timer.adoc @@ -181,4 +181,5 @@ NOTE: To view an example policy project that synchronizes asynchronous periodic == See Also -* xref:policies-pdk-configure-features-inject-parameters.adoc[] \ No newline at end of file +* xref:policies-pdk-configure-features-inject-parameters.adoc[] +* xref:policies-pdk-configure-features-rate-limiting.adoc[] \ No newline at end of file diff --git a/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features.adoc b/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features.adoc index 018796576..b8c88d3df 100644 --- a/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features.adoc +++ b/pdk/1.5/modules/ROOT/pages/policies-pdk-configure-features.adoc @@ -191,6 +191,7 @@ PDK provides code examples for the following policy features. Review <