HallPass 0.0.8
See the version list below for details.
dotnet add package HallPass --version 0.0.8
NuGet\Install-Package HallPass -Version 0.0.8
<PackageReference Include="HallPass" Version="0.0.8" />
paket add HallPass --version 0.0.8
#r "nuget: HallPass, 0.0.8"
// Install HallPass as a Cake Addin
#addin nuget:?package=HallPass&version=0.0.8
// Install HallPass as a Cake Tool
#tool nuget:?package=HallPass&version=0.0.8
HallPass
Client-side rate limiter library for .NET to help client-side developers respect the rate limits of the APIs that they consume.
Installation
// nuget package manager
Install-Package HallPass
// dotnet cli
dotnet add package HallPass
Usage
Suppose you want to consume an API with the endpoint https://api.foo.com/users
, which imposes a rate limit of 10 requests per minute, implemented via a standard Token Bucket algorithm where you can burst 10 requests every minute.
To respect this rate limit in our application, we should create a single IHallMonitor
keyed to this endpoint with the correct IPolicy
:
IPolicy policy = Policies.TokenBucket(requestsPerPeriod: 10, periodDuration: TimeSpan.FromMinutes(1));
IHallMonitor usersMonitor = new LocalHallMonitor("https://api.foo.com/users", policy);
Then, anywhere in our application that needs to rate limit this particular API, we can use our IHallMonitor
like this:
var userId = 13;
FooResult result = await usersMonitor.Request<FooResult>(() => RequestFromFooAsync($"https://api.foo.com/users/{userId}"));
Throttle a Single Call
To throttle a request anywhere in your application, just make sure you're using the same IHallMonitor
for a given endpoint at each place that you want to share the same rate limit.
// somewhere in your configuration
var policy = Policies.TokenBucket(requestsPerPeriod: 10, periodDuration: TimeSpan.FromMinutes(1));
var hallMonitor = new LocalHallMonitor("some/unique/uri/with/a/rate/limit", policy);
// somewhere in your application
FooResult result = await hallMonitor.Request<FooResult>(() => RequestFromExternalApiAsync());
Throttle a Bunch of Calls in a Loop
HallPass works for synchronous loops (within async methods) by simply awaiting until it has permission to proceed based on the provided IPolicy
.
var policy = Policies.TokenBucket(requestsPerPeriod: 10, periodDuration: TimeSpan.FromMinutes(1));
var hallMonitor = new LocalHallMonitor("some/unique/uri/with/a/rate/limit", policy);
var results = new List<FooResult>();
var idsToGet = Enumerable.Range(1, 500);
foreach (var id in idsToGet)
{
FooResult result = await hallMonitor.Request<FooResult>(() => RequestFromExternalApiAsync(id));
results.Add(result);
}
In this example, the first 10 requests would burst immediately, and then the 11th would be awaited for roughly 1 minute, at which point it would burst 11-20... at which point it would wait roughly another minute, etc.
Throttle a Bunch of Calls Concurrently
HallPass is also thread-safe, working as expected for concurrent bunches of requests:
var policy = Policies.TokenBucket(requestsPerPeriod: 10, periodDuration: TimeSpan.FromMinutes(1));
var hallMonitor = new LocalHallMonitor("some/unique/uri/with/a/rate/limit", policy);
var results = new List<FooResult>();
var tasks = Enumerable
.Range(1, 500)
.Select(id => Task.Run(async () =>
{
var result = await hallMonitor.Request<FooResult>(() => RequestFromExternalApiAsync(id));
results.Add(result);
}))
.ToList();
await Task.WhenAll(tasks);
COMING SOON: Throttle a Bunch of Calls Across Distributed Systems
Eventually, HallPass will be able to throttle calls across distributed systems. If you have multiple instances of an application running at once, but need to respect a single external API rate limit, or if you have multiple different applications running but still need to respect a single external API rate limit between all instances and applications, you'd be able to do so like this:
// in the configuration of each of your client instances/applications
var policy = Policies.TokenBucket(requestsPerPeriod: 10, periodDuration: TimeSpan.FromMinutes(1));
var hallMonitor = new DistributedHallMonitor("some/unique/uri/with/a/rate/limit", policy, "your-hallpass-app-key", "your-hallpass-app-secret");
// in your instances/applications
FooResult result = await hallMonitor.Request<FooResult>(() => RequestFromExternalApiAsync());
HallPass will take care of registering individual instances, "fairly" dolling out permissions, and tracking the global rate limit for your account/app and its usage on our servers.
HallPass will never know what endpoints you're calling, because the actual API call is still handled locally within each application. All that HallPass receives is an encrypted unique ID representing each IHallMonitor
's unique key, and the policy used for that key.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 is compatible. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net5.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
0.6.2 | 222 | 5/1/2023 |
0.6.1 | 416 | 8/18/2022 |
0.6.0 | 415 | 8/18/2022 |
0.5.5 | 396 | 8/17/2022 |
0.5.4 | 414 | 8/17/2022 |
0.5.3 | 400 | 8/17/2022 |
0.5.2 | 388 | 8/15/2022 |
0.5.1 | 455 | 8/15/2022 |
0.5.0 | 439 | 8/1/2022 |
0.4.1 | 419 | 7/29/2022 |
0.4.0 | 424 | 7/29/2022 |
0.3.0 | 430 | 7/28/2022 |
0.2.7 | 435 | 7/28/2022 |
0.2.6 | 407 | 7/28/2022 |
0.2.4 | 422 | 7/27/2022 |
0.2.3 | 423 | 7/21/2022 |
0.2.2 | 417 | 7/18/2022 |
0.2.1 | 390 | 7/15/2022 |
0.2.0 | 435 | 7/14/2022 |
0.1.3 | 453 | 7/7/2022 |
0.1.2 | 432 | 7/5/2022 |
0.1.1 | 441 | 6/8/2022 |
0.1.0 | 403 | 6/7/2022 |
0.0.18 | 404 | 6/7/2022 |
0.0.17 | 424 | 6/7/2022 |
0.0.16 | 394 | 6/6/2022 |
0.0.15 | 424 | 6/6/2022 |
0.0.14 | 426 | 6/6/2022 |
0.0.13 | 425 | 6/6/2022 |
0.0.12 | 431 | 6/6/2022 |
0.0.11 | 396 | 6/4/2022 |
0.0.10 | 452 | 6/3/2022 |
0.0.9 | 427 | 5/31/2022 |
0.0.8 | 416 | 5/31/2022 |
0.0.7 | 425 | 5/31/2022 |
0.0.6 | 413 | 5/31/2022 |
0.0.5 | 408 | 5/31/2022 |
0.0.4 | 443 | 5/31/2022 |
0.0.3 | 417 | 5/31/2022 |
0.0.2 | 424 | 5/31/2022 |
0.0.1 | 430 | 5/11/2022 |