W-20012804 pdk 1.5 rate limiting gr

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[]

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. 
 

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[]

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<String>
 == See Also
 
 * xref:policies-pdk-configure-features.adoc[]
+* xref:policies-pdk-configure-features-rate-limiting.adoc[]

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[]
+* xref:policies-pdk-configure-features-inject-parameters.adoc[]
+* xref:policies-pdk-configure-features-rate-limiting.adoc[]

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 <<policy-te
 * 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[]