Merge pull request #25082 from abpframework/enhance/operation-rate-limiting-configure-policy

Add `ConfigurePolicy` and `ClearRules` to Operation Rate Limiting

Author: EngincanV

docs/en/Community-Articles/2026-03-10-Operation-Rate-Limiting-in-ABP-Framework/POST.md

@@ -114,6 +114,70 @@ The two counters are completely independent. If `alice` fails 5 times, her accou
 
 When multiple rules are present, the module uses a two-phase approach: it checks all rules first, and only increments counters if every rule passes. This prevents a rule from consuming quota on a request that would have been rejected by another rule anyway.
 
+## Customizing Policies from Reusable Modules
+
+ABP modules (including your own) can ship with built-in rate limiting policies. For example, an Account module might define a `"Account.SendPasswordResetCode"` policy with conservative defaults that make sense for most applications. When you need different rules in your specific application, you have two options.
+
+**Complete replacement with `AddPolicy`:** call `AddPolicy` with the same name and the second registration wins, replacing all rules from the module:
+
+```csharp
+Configure<AbpOperationRateLimitingOptions>(options =>
+{
+    options.AddPolicy("Account.SendPasswordResetCode", policy =>
+    {
+        policy.AddRule(rule => rule
+            .WithFixedWindow(TimeSpan.FromMinutes(5), maxCount: 3)
+            .PartitionByEmail());
+    });
+});
+```
+
+**Partial modification with `ConfigurePolicy`:** when you only want to tweak part of a policy — change the error code, add a secondary rule, or tighten the window — use `ConfigurePolicy`. The builder starts pre-populated with the module's existing rules, so you only express what changes.
+
+For example, keep the module's default rules but assign your own localized error code:
+
+```csharp
+Configure<AbpOperationRateLimitingOptions>(options =>
+{
+    options.ConfigurePolicy("Account.SendPasswordResetCode", policy =>
+    {
+        policy.WithErrorCode("MyApp:PasswordResetLimit");
+    });
+});
+```
+
+Or add a secondary IP-based rule on top of what the module already defined, without touching it:
+
+```csharp
+Configure<AbpOperationRateLimitingOptions>(options =>
+{
+    options.ConfigurePolicy("Account.SendPasswordResetCode", policy =>
+    {
+        policy.AddRule(rule => rule
+            .WithFixedWindow(TimeSpan.FromHours(1), maxCount: 20)
+            .PartitionByClientIp());
+    });
+});
+```
+
+If you want a clean slate, call `ClearRules()` first and then define entirely new rules — this gives you the same result as `AddPolicy` but makes the intent explicit:
+
+```csharp
+Configure<AbpOperationRateLimitingOptions>(options =>
+{
+    options.ConfigurePolicy("Account.SendPasswordResetCode", policy =>
+    {
+        policy.ClearRules()
+              .WithFixedWindow(TimeSpan.FromMinutes(10), maxCount: 5)
+              .PartitionByEmail();
+    });
+});
+```
+
+`ConfigurePolicy` throws if the policy name doesn't exist — which catches typos at startup rather than silently doing nothing.
+
+The general rule: use `AddPolicy` for full replacements, `ConfigurePolicy` for surgical modifications.
+
 ## Beyond Just Checking
 
 Not every scenario calls for throwing an exception. `IOperationRateLimitingChecker` provides three additional methods for more nuanced control.

docs/en/framework/infrastructure/operation-rate-limiting.md

@@ -115,6 +115,78 @@ options.AddPolicy("Login", policy =>
 
 > When multiple rules are present, the module uses a **two-phase check**: it first verifies all rules without incrementing counters, then increments only if all rules pass. This prevents wasted quota when one rule would block the request.
 
+### Overriding an Existing Policy
+
+If a reusable module (e.g., ABP's Account module) defines a policy with default rules, you have two ways to customize it in your own module's `ConfigureServices`.
+
+**Option 1 — Full replacement with `AddPolicy`:**
+
+Call `AddPolicy` with the same name. The last registration wins and completely replaces all rules:
+
+````csharp
+// In your application module — runs after the Account module
+Configure<AbpOperationRateLimitingOptions>(options =>
+{
+    options.AddPolicy("Account.SendPasswordResetCode", policy =>
+    {
+        // Replaces all rules defined by the Account module for this policy
+        policy.AddRule(rule => rule
+            .WithFixedWindow(TimeSpan.FromMinutes(5), maxCount: 3)
+            .PartitionByEmail());
+    });
+});
+````
+
+> `AddPolicy` stores policies in a dictionary keyed by name, so calling it again with the same name fully replaces the previous policy and all its rules.
+
+**Option 2 — Partial modification with `ConfigurePolicy`:**
+
+Use `ConfigurePolicy` to modify an existing policy without replacing it entirely. The builder is pre-populated with the existing rules, so you only need to express what changes:
+
+````csharp
+Configure<AbpOperationRateLimitingOptions>(options =>
+{
+    // Only override the error code, keeping the module's original rules
+    options.ConfigurePolicy("Account.SendPasswordResetCode", policy =>
+    {
+        policy.WithErrorCode("MyApp:SmsCodeLimit");
+    });
+});
+````
+
+You can also add a rule on top of the existing ones:
+
+````csharp
+options.ConfigurePolicy("Account.SendPasswordResetCode", policy =>
+{
+    // Keep the module's per-email rule and add a per-IP rule on top
+    policy.AddRule(rule => rule
+        .WithFixedWindow(TimeSpan.FromHours(1), maxCount: 20)
+        .PartitionByClientIp());
+});
+````
+
+Or clear all inherited rules first and define entirely new ones using `ClearRules()`:
+
+````csharp
+options.ConfigurePolicy("Account.SendPasswordResetCode", policy =>
+{
+    policy.ClearRules()
+          .WithFixedWindow(TimeSpan.FromMinutes(5), maxCount: 3)
+          .PartitionByEmail();
+});
+````
+
+`ConfigurePolicy` returns `AbpOperationRateLimitingOptions`, so you can chain multiple calls:
+
+````csharp
+options
+    .ConfigurePolicy("Account.SendPasswordResetCode", p => p.WithErrorCode("MyApp:SmsLimit"))
+    .ConfigurePolicy("Account.Login", p => p.WithErrorCode("MyApp:LoginLimit"));
+````
+
+> `ConfigurePolicy` throws `AbpException` if the policy name is not found. Use `AddPolicy` first (in the module that owns the policy), then `ConfigurePolicy` in downstream modules to customize it.
+
 ### Custom Error Code
 
 By default, the exception uses the error code `Volo.Abp.OperationRateLimiting:010001`. You can override it per policy:

framework/src/Volo.Abp.OperationRateLimiting/Volo/Abp/OperationRateLimiting/AbpOperationRateLimitingOptions.cs

@@ -11,10 +11,38 @@ public class AbpOperationRateLimitingOptions
 
     public Dictionary<string, OperationRateLimitingPolicy> Policies { get; } = new();
 
-    public void AddPolicy(string name, Action<OperationRateLimitingPolicyBuilder> configure)
+    public AbpOperationRateLimitingOptions AddPolicy(string name, Action<OperationRateLimitingPolicyBuilder> configure)
     {
+        Check.NotNullOrWhiteSpace(name, nameof(name));
+        Check.NotNull(configure, nameof(configure));
+
         var builder = new OperationRateLimitingPolicyBuilder(name);
         configure(builder);
         Policies[name] = builder.Build();
+        return this;
+    }
+
+    /// <summary>
+    /// Configures an existing rate limiting policy by name.
+    /// The builder is pre-populated with the existing policy's rules and error code,
+    /// so you can add, clear, or replace rules while keeping what you don't change.
+    /// Throws <see cref="AbpException"/> if the policy is not found.
+    /// </summary>
+    public AbpOperationRateLimitingOptions ConfigurePolicy(string name, Action<OperationRateLimitingPolicyBuilder> configure)
+    {
+        Check.NotNullOrWhiteSpace(name, nameof(name));
+        Check.NotNull(configure, nameof(configure));
+
+        if (!Policies.TryGetValue(name, out var existingPolicy))
+        {
+            throw new AbpException(
+                $"Could not find operation rate limiting policy: '{name}'. " +
+                "Make sure the policy is defined with AddPolicy() before calling ConfigurePolicy().");
+        }
+
+        var builder = OperationRateLimitingPolicyBuilder.FromPolicy(existingPolicy);
+        configure(builder);
+        Policies[name] = builder.Build();
+        return this;
     }
 }

framework/src/Volo.Abp.OperationRateLimiting/Volo/Abp/OperationRateLimiting/Policies/OperationRateLimitingPolicyBuilder.cs

@@ -62,6 +62,29 @@ public OperationRateLimitingPolicyBuilder WithErrorCode(string errorCode)
         return this;
     }
 
+    /// <summary>
+    /// Clears all rules and custom rule types from this policy builder,
+    /// allowing a full replacement of the inherited rules.
+    /// </summary>
+    /// <returns>The current builder instance for method chaining.</returns>
+    public OperationRateLimitingPolicyBuilder ClearRules()
+    {
+        _rules.Clear();
+        _customRuleTypes.Clear();
+        return this;
+    }
+
+    internal static OperationRateLimitingPolicyBuilder FromPolicy(OperationRateLimitingPolicy policy)
+    {
+        Check.NotNull(policy, nameof(policy));
+
+        var builder = new OperationRateLimitingPolicyBuilder(policy.Name);
+        builder._errorCode = policy.ErrorCode;
+        builder._rules.AddRange(policy.Rules);
+        builder._customRuleTypes.AddRange(policy.CustomRuleTypes);
+        return builder;
+    }
+
     internal void AddRuleDefinition(OperationRateLimitingRuleDefinition definition)
     {
         _rules.Add(definition);