[API Proposal]: RateLimitPartition rename Create methods

[BrennanConroy]

Background and motivation

As part of #65400 we made a RateLimitPartition API which holds information about a partitions key and a factory to create a RateLimiter if the partition isn't currently instantiated.

The current API is RateLimitPartition.Create<TKey>(TKey partitionKey, Func<TKey, RateLimiter> factory) and .CreateConcurrencyLimiter<TKey>(...) .CreateNoLimiter<TKey>(...) etc. for specific limiters we provide. The concern is that the "Create" names imply the limiters are being created every time the RateLimitPartition.Create(...) method is called which isn't true.

We would like to propose renaming these methods to try to be clearer that it's a partition identifier+creator that is being created.

API Proposal

namespace System.Threading.RateLimiting;

public static class RateLimitPartition
{
-    public static RateLimitPartition<TKey> Create<TKey>(
+    public static RateLimitPartition<TKey> Define<TKey>(
        TKey partitionKey,
        Func<TKey, RateLimiter> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateConcurrencyLimiter<TKey>(
+    public static RateLimitPartition<TKey> DefineConcurrencyLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, ConcurrencyLimiterOptions> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateNoLimiter<TKey>(TKey partitionKey)
+    public static RateLimitPartition<TKey> DefineNoLimiter<TKey>(TKey partitionKey)
    {
    }

-    public static RateLimitPartition<TKey> CreateTokenBucketLimiter<TKey>(
+    public static RateLimitPartition<TKey> DefineTokenBucketLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, TokenBucketRateLimiterOptions> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateSlidingWindowLimiter<TKey>(
+    public static RateLimitPartition<TKey> DefineSlidingWindowLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, SlidingWindowRateLimiterOptions> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateFixedWindowLimiter<TKey>(
+    public static RateLimitPartition<TKey> DefineFixedWindowLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, FixedWindowRateLimiterOptions> factory)
    {
    }

API Usage

PartitionedRateLimiter<string> limiter = PartitionedRateLimiter.Create<string, string>(resource =>
{
    switch (resource)
    {
        case "Policy1":
            return RateLimitPartition.DefineConcurrencyLimiter(resource, _ => new ConcurrencyLimiterOptions(...));
        case "Policy2":
            return RateLimitPartition.DefineTokenBucketLimiter(resource, _ => new TokenBucketRateLimiterOptions(...));
        default:
            return RateLimitPartition.Define(resource, _ => new CustomLimiter(...));
    }
});

RateLimitLease lease = limiter.Acquire("Policy1");
// etc.

Alternative Designs

+    public static RateLimitPartition<TKey> Choose<TKey>(...);
+    public static RateLimitPartition<TKey> ChooseConcurrencyLimiter<TKey>(...);
+    public static RateLimitPartition<TKey> ChooseNoLimiter<TKey>(...);

---

+    public static RateLimitPartition<TKey> With<TKey>(...);
+    public static RateLimitPartition<TKey> WithConcurrencyLimiter<TKey>(...);
+    public static RateLimitPartition<TKey> WithNoLimiter<TKey>(...);

---

+    public static RateLimitPartition<TKey> DefinePartition<TKey>(...);
+    public static RateLimitPartition<TKey> DefineConcurrencyLimiterPartition<TKey>(...);
+    public static RateLimitPartition<TKey> DefineNoLimiterPartition<TKey>(...);

---

+    public static RateLimitPartition<TKey> GetOrCreate<TKey>(...);
+    public static RateLimitPartition<TKey> GetOrCreateConcurrencyLimiter<TKey>(...);
+    public static RateLimitPartition<TKey> GetOrCreateNoLimiter<TKey>(...);

Risks

No response

[ghost]

Tagging subscribers to this area: @mangod9
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

As part of #65400 we made a RateLimitPartition API which holds information about a partitions key and a factory to create a RateLimiter if the partition isn't currently instantiated.

The current API is RateLimitPartition.Create<TKey>(TKey partitionKey, Func<TKey, RateLimiter> factory) and .CreateConcurrencyLimiter<TKey>(...) .CreateNoLimiter<TKey>(...) etc. for specific limiters we provide. The concern is that the "Create" names imply the limiters are being created every time the RateLimitPartition.Create(...) method is called which isn't true.

We would like to propose renaming these methods to try to be clearer that it's a partition identifier+creator that is being created.

API Proposal

namespace System.Threading.RateLimiting;

public static class RateLimitPartition
{
-    public static RateLimitPartition<TKey> Create<TKey>(
+    public static RateLimitPartition<TKey> Define<TKey>(
        TKey partitionKey,
        Func<TKey, RateLimiter> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateConcurrencyLimiter<TKey>(
+    public static RateLimitPartition<TKey> DefineConcurrencyLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, ConcurrencyLimiterOptions> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateNoLimiter<TKey>(TKey partitionKey)
+    public static RateLimitPartition<TKey> DefineNoLimiter<TKey>(TKey partitionKey)
    {
    }

-    public static RateLimitPartition<TKey> CreateTokenBucketLimiter<TKey>(
+    public static RateLimitPartition<TKey> DefineTokenBucketLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, TokenBucketRateLimiterOptions> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateSlidingWindowLimiter<TKey>(
+    public static RateLimitPartition<TKey> DefineSlidingWindowLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, SlidingWindowRateLimiterOptions> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateFixedWindowLimiter<TKey>(
+    public static RateLimitPartition<TKey> DefineFixedWindowLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, FixedWindowRateLimiterOptions> factory)
    {
    }

API Usage

PartitionedRateLimiter<string> limiter = PartitionedRateLimiter.Create<string, string>(resource =>
{
    switch (resource)
    {
        case "Policy1":
            return RateLimitPartition.DefineConcurrencyLimiter(resource, _ => new ConcurrencyLimiterOptions(...));
        case "Policy2":
            return RateLimitPartition.DefineTokenBucketLimiter(resource, _ => new TokenBucketRateLimiterOptions(...));
        default:
            return RateLimitPartition.Define(resource, _ => new CustomLimiter(...));
    }
});

RateLimitLease lease = limiter.Acquire("Policy1");
// etc.

Alternative Designs

+    public static RateLimitPartition<TKey> Choose<TKey>(...);
+    public static RateLimitPartition<TKey> ChooseConcurrencyLimiter<TKey>(...);
+    public static RateLimitPartition<TKey> ChooseNoLimiter<TKey>(...);

---

+    public static RateLimitPartition<TKey> With<TKey>(...);
+    public static RateLimitPartition<TKey> WithConcurrencyLimiter<TKey>(...);
+    public static RateLimitPartition<TKey> WithNoLimiter<TKey>(...);

---

+    public static RateLimitPartition<TKey> DefinePartition<TKey>(...);
+    public static RateLimitPartition<TKey> DefineConcurrencyLimiterPartition<TKey>(...);
+    public static RateLimitPartition<TKey> DefineNoLimiterPartition<TKey>(...);

---

+    public static RateLimitPartition<TKey> GetOrCreate<TKey>(...);
+    public static RateLimitPartition<TKey> GetOrCreateConcurrencyLimiter<TKey>(...);
+    public static RateLimitPartition<TKey> GetOrCreateNoLimiter<TKey>(...);

Risks

No response

Author:	BrennanConroy
Assignees:	-
Labels:	api-suggestion, area-System.Threading
Milestone:	-

[terrajobst]

Video

• Let' use Get

namespace System.Threading.RateLimiting;

public static class RateLimitPartition
{
-    public static RateLimitPartition<TKey> Create<TKey>(
+    public static RateLimitPartition<TKey> Get<TKey>(
        TKey partitionKey,
        Func<TKey, RateLimiter> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateConcurrencyLimiter<TKey>(
+    public static RateLimitPartition<TKey> GetConcurrencyLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, ConcurrencyLimiterOptions> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateNoLimiter<TKey>(TKey partitionKey)
+    public static RateLimitPartition<TKey> GetNoLimiter<TKey>(TKey partitionKey)
    {
    }

-    public static RateLimitPartition<TKey> CreateTokenBucketLimiter<TKey>(
+    public static RateLimitPartition<TKey> GetTokenBucketLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, TokenBucketRateLimiterOptions> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateSlidingWindowLimiter<TKey>(
+    public static RateLimitPartition<TKey> GetSlidingWindowLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, SlidingWindowRateLimiterOptions> factory)
    {
    }

-    public static RateLimitPartition<TKey> CreateFixedWindowLimiter<TKey>(
+    public static RateLimitPartition<TKey> GetFixedWindowLimiter<TKey>(
        TKey partitionKey,
        Func<TKey, FixedWindowRateLimiterOptions> factory)
    {
    }