rlqs: update and document failure mode behaviors (#30581)

* rlqs: update and document failure mode behaviors

RLQS documentation updates intended to prevent memory exhaustion
caused by the number of tracked buckets.

- Changes the default behavior of unset
  ExpiredAssignmentBehavior.expired_assignment_behavior_timeout from
  "retain unlimited time" to "abandon immediately"
- Clarifies the retention policy for the buckets that never received
  the initial assignment.
- Clarifies the implementation details for evicting buckets that
  never received the initial assignment.

---------

Signed-off-by: Sergii Tkachenko <sergiitk@google.com>

Mirrored from https://github.com/envoyproxy/envoy @ 487f57ddc4a1d47828a5c8ceee91a08a879fc6dd

envoy/extensions/filters/http/rate_limit_quota/v3/rate_limit_quota.proto

@@ -202,8 +202,7 @@ message RateLimitQuotaBucketSettings {
     //    <envoy_v3_api_msg_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.AbandonAction>`
     //    message.
     //
-    // If the field is not set, the ``ExpiredAssignmentBehavior`` time is **not limited**:
-    // it applies to the bucket until replaced by an ``active`` assignment.
+    // If not set, defaults to zero, and the bucket is abandoned immediately.
     google.protobuf.Duration expired_assignment_behavior_timeout = 1
         [(validate.rules).duration = {gt {}}];
 
@@ -389,6 +388,12 @@ message RateLimitQuotaBucketSettings {
   //
   // After sending the initial report, the data plane is to continue reporting the bucket usage with
   // the internal specified in this field.
+  //
+  // If for any reason RLQS client doesn't receive the initial assignment for the reported bucket,
+  // the data plane will eventually consider the bucket abandoned and stop sending the usage
+  // reports. This is explained in more details at :ref:`Rate Limit Quota Service (RLQS)
+  // <envoy_v3_api_file_envoy/service/rate_limit_quota/v3/rlqs.proto>`.
+  //
   // [#comment: 100000000 nanoseconds = 0.1 seconds]
   google.protobuf.Duration reporting_interval = 2 [(validate.rules).duration = {
     required: true

envoy/service/rate_limit_quota/v3/rlqs.proto

@@ -43,6 +43,14 @@ option (xds.annotations.v3.file_status).work_in_progress = true;
 // <envoy_v3_api_field_service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.abandon_action>`
 // it.
 //
+// If for any reason the RLQS client doesn't receive the initial assignment for the reported bucket,
+// in order to prevent memory exhaustion, the data plane will limit the time such bucket
+// is retained. The exact time to wait for the initial assignment is chosen by the filter,
+// and may vary based on the implementation.
+// Once the duration ends, the data plane will stop reporting bucket usage, reject any enqueued
+// requests, and purge the bucket from the memory. Subsequent requests matched into the bucket
+// will re-initialize the bucket in the "no assignment" state, restarting the reports.
+//
 // Refer to Rate Limit Quota :ref:`configuration overview <config_http_filters_rate_limit_quota>`
 // for further details.