Skip to content
Meddle Docs

Rate Limiter Connector

Overview

Section titled “Overview”

The Rate Limiter connector caps the rate at which payloads flow through a pipeline using a token-bucket algorithm. It supports two strategies: dropping excess payloads, or queueing them for later delivery.

Connector Type: MeddleRateLimiter

Drop Strategy

Section titled “Drop Strategy”

Excess payloads are discarded immediately and reported on the error channel.

{
  "type": "MeddleRateLimiter",
  "config": {
    "maxRate": 10,
    "burstSize": 20,
    "strategy": "drop"
  }
}

Allows up to 10 events per second, with bursts of up to 20. When the bucket is empty, incoming payloads are dropped.

Queue Strategy

Section titled “Queue Strategy”

Excess payloads are buffered in a bounded queue and drained at the configured rate.

{
  "type": "MeddleRateLimiter",
  "config": {
    "maxRate": 5,
    "burstSize": 5,
    "strategy": "queue",
    "queueSize": 200
  }
}

If the queue is full, additional payloads are reported on the error channel as an overflow.

Configuration Parameters

Section titled “Configuration Parameters”
  • maxRate (required, > 0): Sustained throughput in events per second (float)
  • burstSize (required, > 0): Maximum burst capacity of the token bucket
  • strategy (required): drop or queue
  • queueSize: Queue capacity for queue strategy (default 100)

Token-Bucket Semantics

Section titled “Token-Bucket Semantics”
  • The bucket holds at most burstSize tokens and refills at maxRate tokens per second
  • Each payload consumes one token
  • Under drop, a payload is forwarded immediately if a token is available; otherwise it is discarded
  • Under queue, the payload is enqueued, then forwarded as soon as the next token is granted. Overflow occurs when the queue is full.

Use Cases

Section titled “Use Cases”
  1. Protect downstream APIs with strict rate limits (e.g. third-party SaaS endpoints)
  2. Smooth bursty inputs before writing to a database
  3. Cap notification frequency to avoid alert storms
  4. Throttle outbound webhooks to stay under provider quotas

Example: Smoothing a Bursty MQTT Stream

Section titled “Example: Smoothing a Bursty MQTT Stream”
{
  "type": "MeddleRateLimiter",
  "config": {
    "maxRate": 50,
    "burstSize": 100,
    "strategy": "queue",
    "queueSize": 1000
  }
}

Sustains 50 events/sec with a 100-event burst headroom. Up to 1000 events may queue during peak traffic before overflow.

Example: Drop Excess Alerts

Section titled “Example: Drop Excess Alerts”
{
  "type": "MeddleRateLimiter",
  "config": {
    "maxRate": 1,
    "burstSize": 1,
    "strategy": "drop"
  }
}

At most one payload per second is forwarded; anything above that is silently dropped (with an error logged).

Best Practices

Section titled “Best Practices”
  • Match maxRate to the slowest downstream consumer’s documented limit, with headroom
  • Use drop when freshness matters more than completeness (e.g. live dashboards)
  • Use queue when no payload can be lost; size the queue to absorb expected burst durations
  • Monitor the error channel — dropped/overflowed payloads are reported there
  • Combine with On Change to first remove duplicates, then rate-limit unique events
Section titled “Related Connectors”