rate-limit

Overview

The rate-limit node controls message throughput by enforcing a maximum number of messages per time window. Unlike the delay node which spaces messages evenly, rate-limit uses a counter-based approach: it tracks how many messages have passed within the current window and applies a strategy (drop, queue, or delay) when the limit is exceeded. Ideal for API rate compliance, notification throttling, and protecting downstream services from burst traffic.

Properties

Overflow Strategies

// Rate: 3/window
In:  1 2 3 4 5 | 6 7 8
Out: 1 2 3 X X | 6 7 8
     ^^^^^^^^^^   ^^^^^
     window 1     window 2
(4 and 5 are dropped)

// Rate: 3/window
In:  1 2 3 4 5 | next window
Out: 1 2 3     | 4 5 ...
     (4, 5 queued and sent
      when window resets)

// Rate: 3/window
In:  1 2 3 4 5
Out: 1 2 3 ─wait─ 4 5
     (4 waits for next window,
      back-pressure applied)

Rate Limit vs Delay Node

Counts messages per window.
100 msgs/minute = allows bursts
of up to 100, then blocks until
the minute resets.

Best for: API rate limits,
quota enforcement.

Spaces messages evenly.
100 msgs/minute = 1 message
every 600ms, steady flow.

Best for: smooth output,
LED sequences, UI updates.

Example: Limit API Calls to 100/Minute

Enforce external API rate limits to avoid HTTP 429 errors.

// Rate-limit node configuration
{
  "rate": 100,
  "timeWindow": "minute",
  "strategy": "queue",
  "maxQueue": 500
}

// Flow: sensor data → rate-limit → http-request (external API)
//
// Sensors generate ~200 msgs/min during peak
// API allows max 100 requests/minute
//
// Behavior:
//   0:00 - 0:30  → 100 messages pass (burst allowed)
//   0:30 - 1:00  → excess queued (limit reached)
//   1:00 onward  → queued messages drain, no 429 errors

Example: Throttle Notification Emails

Prevent alert fatigue by limiting email notifications to 5 per hour.

// Rate-limit node configuration
{
  "rate": 5,
  "timeWindow": "hour",
  "strategy": "drop",
  "septopics": true    // Separate limits per alert type
}

// Flow: alert-engine → rate-limit → email node
//
// Without rate-limit:
//   Temperature alarm fires every 30 seconds
//   = 120 emails per hour!
//
// With rate-limit (drop strategy):
//   First 5 alerts → email sent
//   Next 115 alerts → silently dropped
//   Next hour → counter resets, 5 more allowed
//
// septopics: true means each alert type
// (temperature, humidity, pressure) gets its own
// 5/hour allowance independently

Common Use Cases