Skip to content

Latest commit

 

History

History
116 lines (82 loc) · 2.89 KB

tpl.readme.md

File metadata and controls

116 lines (82 loc) · 2.89 KB

About

{{pkg.description}}

Leaky Buckets are commonly used in communication networks for rate limiting, traffic shaping and bandwidth control, but are equally useful in other domains requiring similar constraints.

A Leaky Bucket is a managed counter with an enforced maximum value (i.e. bucket capacity). The counter is incremented for each a new event to check if it can/should be processed. If the bucket capacity has already been reached, the bucket will report an overflow, which we can then handle accordingly (e.g. by dropping or queuing events). The bucket also has a configurable time interval at which the counter is decreasing (aka the "leaking" behavior) until it reaches zero again (i.e. until the bucket is empty). Altogether, this setup can be utilized to ensure both an average rate, whilst also supporting temporary bursting in a controlled fashion.

import { LeakyBucket } from "@thi.ng/leaky-bucket";

// create bucket w/ 1Hz mean target rate, burstable to 3Hz
const bucket = new LeakyBucket({ capacity: 3, leakInterval: 1000 });

let event = 0;
let t0 = Date.now();

// trigger events at 5Hz
setInterval(() => {
	event++;
	// update bucket and only log successful events (discard the rest)
	if (bucket.update()) {
		console.log("time", Date.now() - t0, "/ event", event);
	}
}, 200);

// time 200 / event 1   <-- initial burst
// time 401 / event 2   <-- initial burst
// time 601 / event 3   <-- initial burst
// time 1003 / event 5  <-- average rate enforced
// time 2007 / event 10
// time 3012 / event 15
// time 4017 / event 20
// ...

In addition to individual LeakyBuckets, this package also provides a LeakyBucketMap for managing multiple buckets in a key-value store, with shared configuration and more efficient updates (only using a single timer). Other features include:

  • enforces max number of active (non-empty) buckets
  • auto-pruning of empty buckets
  • auto-creation of new buckets
  • per-bucket capacity overrides

{{meta.status}}

{{repo.supportPackages}}

{{repo.relatedPackages}}

{{meta.blogPosts}}

Installation

{{pkg.install}}

{{pkg.size}}

Dependencies

{{pkg.deps}}

{{repo.examples}}

API

{{pkg.docs}}

import { LeakyBucketMap } from "@thi.ng/leaky-bucket";

const buckets = new LeakyBucketMap({
	maxBuckets: 2,
	capacity: 3,
	leakInterval: 1000,
});

buckets.update("a") // true
buckets.update("a") // true
buckets.update("a") // true

// max capacity=3 reached
buckets.update("a"); // false

// another bucket
buckets.update("b"); // true

// max buckets=2 reached
buckets.update("c"); // false

// wait > 1000ms, buckets have leaked...

// bucket A has capacity again
buckets.update("a"); // true

// bucket B has been removed (since emtpy)
buckets.has("b"); // false